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
--
Posted via http://www.ruby-forum.com/.
p :you # can do this....
On Jul 24, 2008, at 3:49 PM, Mike Schwab 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
--
we can deny everything, except that we have the possibility of being better. simply reflect on that.
h.h. the 14th dalai lama
Mike Schwab 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.
--
RMagick: http://rmagick.rubyforge.org/
ha ha sorry if I was unclear. I meant comments that can have more code
after them on the same line.
--
Posted via http://www.ruby-forum.com/.
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.
--
Posted via http://www.ruby-forum.com/\.
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?
On Thu, Jul 24, 2008 at 4:57 PM, Mike Schwab <mike.schwab@gmail.com> wrote:
ha ha sorry if I was unclear. I meant comments that can have more code
after them on the same line.
--
Posted via http://www.ruby-forum.com/\.
* Mike Schwab, 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
--
Blog: http://penpen.goodaddress.eu/
PGP key (id 6CC6574F): http://wwwkeys.de.pgp.net/
Jabber - http://www.jabber.org/ - contact information on request
Mike Schwab wrote:
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.
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 */.
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.
This is a case of Ruby nudging you to name your variables/methods better 
On Thu, Jul 24, 2008 at 9:05 PM, Mike Schwab <mike.schwab@gmail.com> 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.
--
Avdi
Home: http://avdi.org
Developer Blog: Avdi Grimm, Code Cleric
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com
There is no general case, but you can do terrible things if you must, e.g.
x += "x means total but I was too lazy to name it such" && 42
There is no way to bare such crime 
Cheers
Robert
On Thu, Jul 24, 2008 at 11:57 PM, Mike Schwab <mike.schwab@gmail.com> wrote:
ha ha sorry if I was unclear. I meant comments that can have more code
after them on the same line.
--
Posted via http://www.ruby-forum.com/\.
--
http://ruby-smalltalk.blogspot.com/
There's no one thing that's true. It's all true.
--
Ernest Hemingway
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 <hjast89@gmail.com> 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?On Thu, Jul 24, 2008 at 4:57 PM, Mike Schwab <mike.schwab@gmail.com> wrote:
ha ha sorry if I was unclear. I meant comments that can have more code
after them on the same line.
--
Posted via http://www.ruby-forum.com/\.
--
http://jeremymcanally.com/
http://entp.com/
My books:
http://humblelittlerubybook.com/ (FREE!)
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!
--
Posted via http://www.ruby-forum.com/.
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?
--
RMagick: http://rmagick.rubyforge.org/
# 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,
<code>
# add line charges to total t
t += c1 + c2 + misc
<or>
t += c1 + c2 + misc # add line charges to total t
<or>
# total charges t equals
t += c1 + # line charge 1 plus
c2 + # line charge 2 plus
misc # miscellaneous
</code>
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: Michael W. Ryder [mailto:_mwryder@worldnet.att.net]
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 <botp@delmonte-phil.com> wrote:
From: Michael W. Ryder [mailto:_mwryder@worldnet.att.net]
# 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,
<code>
# add line charges to total t
t += c1 + c2 + misc<or>
t += c1 + c2 + misc # add line charges to total t
<or>
# total charges t equals
t += c1 + # line charge 1 plus
c2 + # line charge 2 plus
misc # miscellaneous</code>
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
--
http://jeremymcanally.com/
http://entp.com/
My books:
http://humblelittlerubybook.com/ (FREE!)
Peña wrote:
From: Michael W. Ryder [mailto:_mwryder@worldnet.att.net] # 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,
<code>
# add line charges to total t
t += c1 + c2 + misc<or>
t += c1 + c2 + misc # add line charges to total t
<or>
# total charges t equals
t += c1 + # line charge 1 plus
c2 + # line charge 2 plus
misc # miscellaneous</code>
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.
Kind regards -botp
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!
That's more a question of programmer discipline than of having inline comments available. I doubt there is much good code around that actually comments /in line/. If you have an expression that large that you need to individually comment on parts then you probably either choose bad variable names or crafted a too complex expression in the first place.
Note also that you can break up expressions in a way that you can use line comments to comment parts if you wish so:
robert@fussel ~
$ ruby <<XXX
> x = 1 + # basic offset
> 10 + # another unimportant number
> 123 # the final value
> puts x
> XXX
134
robert@fussel ~
$
A similar thing can be done with regular expressions using /x switch.
Kind regards
robert
On 25.07.2008 00:30, Mike Schwab wrote:
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 Thomas and Andy Hunt 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.
On Thu, Jul 24, 2008 at 11:22 PM, Peña, Botp <botp@delmonte-phil.com> 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 ...
--
Avdi
Home: http://avdi.org
Developer Blog: http://avdi.org/devblog/
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com
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.
On Fri, 2008-07-25 at 13:02 +0900, Avdi Grimm wrote:
--
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