Are inline comments a potential feature of Ruby 2.0?
Are there particular syntax or performance issues that preclude this?
With a language where so much fits into one line it could be cool to
document method calls more individually at times.
-Mike
On Jul 24, 2008, at 3:49 PM, Mike S. wrote:
Are inline comments a potential feature of Ruby 2.0?
Are there particular syntax or performance issues that preclude this?
With a language where so much fits into one line it could be cool to
document method calls more individually at times.-Mike
p :you # can do this…
you mean like /* and */ in Java or C#. That isn’t ruby and makes the
code
harder to follow. Why not just comment the line above it. But do wish
there
were block comments, is that in the works?
ha ha sorry if I was unclear. I meant comments that can have more code
after them on the same line.
- Mike S., 2008-07-25, 06:57:
ha ha sorry if I was unclear. I meant comments that can have more
code after them on the same line.
I am confident that Matz will oppose that idea. Such comments almost
for certain result in messy code.
Josef ‘Jupp’ Schugt
fair point, it can make things hard to read if you’re not careful
my main concern is that so much code goes uncommented, and the rdoc
comments being outside the body of the method contributes to an attitude
that allows this.
so many of the quality ruby libraries are so flexible and so meta that
it would be great to have more blow-by-blow explanations sometimes!
Mike S. wrote:
Are inline comments a potential feature of Ruby 2.0?
Are there particular syntax or performance issues that preclude this?
With a language where so much fits into one line it could be cool to
document method calls more individually at times.-Mike
If you have so much code on one line that you feel the need for inline
comments, you could, you know, break it up into multiple lines.
There’s an old saying about C programming: Removing white space does not
make your program run faster.
reuben doetsch wrote:
you mean like /* and */ in Java or C#. That isn’t ruby and makes the code
harder to follow. Why not just comment the line above it. But do wish there
were block comments, is that in the works?
You mean other than =begin and =end?
BLOCK COMMENTS ARE FOR THE WEAK.
But you can do them like this if you have to…
=begin
This is my comment. Lame.
Totally lame.
=end
But I think that’s sort of ugly.
–Jeremy
On Thu, Jul 24, 2008 at 5:14 PM, reuben doetsch [email protected]
wrote:
–
http://jeremymcanally.com/
http://entp.com/
http://omgbloglol.com
My books:
http://manning.com/mcanally/
http://humblelittlerubybook.com/ (FREE!)
If you have so much code on one line that you feel the need for inline
comments, you could, you know, break it up into multiple lines.
my point was about other peoples’ code, including much of the stuff
written by those whose thorough style I admire. It’s not that there’s
too much on the lines. It’s just that sometimes it would be nice to
throw an extra word or two in there. Ruby is supposed to read like
English. sometimes it would be totally appropriate to spruce up your
grammar or clarify your nouns by putting comments in between your
variables, methods, hash keys and class names.
I know that adding a crutch can have severe consequences and Matz has
made important compromises that have worked out extremely well. In fact
I think one of the most significant was his work on disambiguation that
allows us to usually forego parentheses. Writing without parens not
only makes the code more readable, it gives you natural clues about when
things are ready to go on to the next line. You basically do one thing
on each line, usually call one method on each line (and then call
methods to provide its arguments). Sometimes the line gets long, but
sometimes that’s right for the situation. I feel that the more tools
you can use, the more able you are to find the right one for each
situation. Short lines are a great tool but code shouldn’t be penalized
for using long, descriptive names and offering bountiful options, or for
programming functionally and with procs. I know these can all be moved
onto more lines to facilitate comments, and I do this, but how often do
you see the comments there? I tend to feel that if the trade-offs
aren’t too big, we could adopt this feature and let some people try it
and others ignore it. I can only guess that it would slow down the
interpreter and therefore is an unlikely addition, but if that’s not the
case maybe it’s worth a second thought as you read through all the code
you see on github during the next week.
I’m reminded of one day when I suggested that it would be cool to have
highlighting that could alert you when you needed to add parentheses in
order to get the precedence you wanted. Like now, I wasn’t looking for
a lecture. I was just admiring Ruby’s ability to nudge you in the right
direction, and speculating about how we could maybe make it even
stronger and more accessible.
Mike S. wrote:
The best way to provide in-line documentation is to use names that
document what you are doing. Instead of writing x += y, writing:
total_bill = total_bill + line_charge would make it far easier to find a
problem when the figures were wrong. I think it is much clearer than
using something like: x /* total bill amount / += y / line charge */.
total_charges = line_charge_1 + line_charge_2 + misc_charges
No comments needed…?
–Jeremy
On Thu, Jul 24, 2008 at 9:43 PM, Peña, Botp [email protected] wrote:
# total charges t equals
# charge */.
ouch, that is too much. Is that a regex or what? 
Kind regards -botp
–
http://jeremymcanally.com/
http://entp.com/
http://omgbloglol.com
My books:
http://manning.com/mcanally/
http://humblelittlerubybook.com/ (FREE!)
Peña wrote:
# total charges t equals
t += c1 + # line charge 1 plus
c2 + # line charge 2 plus
misc # miscellaneous
Personally, I find this much harder to read, especially if you are
looking through many lines of code for a spelling error.
nonetheless, style is in the eye of the beholder
I think it is much clearer than
using something like: x /* total bill amount / += y / line
charge */.
ouch, that is too much. Is that a regex or what?
No, I just included C style comments in-line. Obviously this was an
excessive example, but it does show the abuse that could happen with
in-line comments and why they would be much harder to read than using
good variable and method names.
On Thu, Jul 24, 2008 at 9:05 PM, Mike S. [email protected]
wrote:
I’m reminded of one day when I suggested that it would be cool to have
highlighting that could alert you when you needed to add parentheses in
order to get the precedence you wanted. Like now, I wasn’t looking for
a lecture. I was just admiring Ruby’s ability to nudge you in the right
direction, and speculating about how we could maybe make it even
stronger and more accessible.
This is a case of Ruby nudging you to name your variables/methods better
–
Avdi
Home: http://avdi.org
Developer Blog: http://avdi.org/devblog/
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com
From: Michael W. Ryder [mailto:[email protected]]
The best way to provide in-line documentation is to use names that
document what you are doing. Instead of writing x += y, writing:
total_bill = total_bill + line_charge would make it far
easier to find a problem when the figures were wrong.
indeed.
on my case, i want simple vars, so,
add line charges to total t
t += c1 + c2 + misc
t += c1 + c2 + misc # add line charges to total t
total charges t equals
t += c1 + # line charge 1 plus
c2 + # line charge 2 plus
misc # miscellaneous
nonetheless, style is in the eye of the beholder 
I think it is much clearer than
using something like: x /* total bill amount / += y / line
charge */.
ouch, that is too much. Is that a regex or what?
Kind regards -botp
From: Jeremy McAnally [mailto:[email protected]]
total_charges = line_charge_1 + line_charge_2 + misc_charges
No comments needed…?
indeed, but as i said, i prefer short variable names. I am relaxed
on object and methods names however, eg, attributes may be more
descriptive …
so i prefer this,
add line charges to total t
t += c1 + c2 + misc
or this,
add line charges to total
def total
charge.first + charge.last + charge.misc
end
again, it’s just style.
kind regards -botp
On Fri, 2008-07-25 at 13:02 +0900, Avdi G. wrote:
Consider also that your clarifying comments may become obfuscating
comments when a global search and replace replaces the variable name
but not the comment.
Global search and replace is a poor substitute for refactoring.
–
M. Edward (Ed) Borasky
ruby-perspectives.blogspot.com
“A mathematician is a machine for turning coffee into theorems.” –
Alfréd Rényi via Paul Erdős
On Fri, Jul 25, 2008 at 12:15 AM, M. Edward (Ed) Borasky
[email protected] wrote:
Global search and replace is a poor substitute for refactoring.
No argument there, but my comment goes equally for the Rename
refactoring.
–
Avdi
Home: http://avdi.org
Developer Blog: http://avdi.org/devblog/
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com
On Thu, Jul 24, 2008 at 11:22 PM, Peña, Botp [email protected]
wrote:
indeed, but as i said, i prefer short variable names. I am relaxed on object and methods names however, eg, attributes may be more descriptive …
Look out, classic appeal to authority coming up:
“Names that are too short don’t convey enough meaning. The problem
with names like X1 and X2 is that even if you can discover what X is,
you won’t know anything about the relationship between X1 and X2…
Gorla, Benander, and Benander found that the effort to debug… was
minimized when variables had names that averaged 10 to 16 characters
(1990)”
– Steve McConnel, Code Complete
“A name should be informative, concise, memorable, and pronounceable
if possible”
– Brian Kernighan and Rob Pike, The Practice of Programming
IIRC The Pragmatic Programmer by Dave T. and Andy H. contains
similar advice, but I don’t have a copy of it handy (it stays by my
desk at work).
It is worth considering that if your favored style leads to unclear
code in your favored language, it may be time to reconsider your
favored style.
Consider also that your clarifying comments may become obfuscating
comments when a global search and replace replaces the variable name
but not the comment.
–
Avdi
Home: http://avdi.org
Developer Blog: http://avdi.org/devblog/
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com
From: [email protected] [mailto:[email protected]] On
It is worth considering that if your favored style leads to unclear
code in your favored language, it may be time to reconsider your
favored style.
maybe, i was not clear enough. When a short var, like x is clear enough
in the context of the set of codes it will be used, then i use it. And
since i tend to code short (less than 20 lines) of methods/functions, i
do frequently use short var names. I do not like strict enforcing
“longer names always better” rule…
eg,
5.times{|number_element| p number_element}
vs
5.times{|x| p x}
names_of_people.each{…}
vs
names.each{…}
i hope i am clear enough now.
kind regards -botp