inline comments in future release?

M

Mike Schwab

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
 
A

ara.t.howard

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....


a @ http://codeforpeople.com/
 
M

Mike Schwab

ha ha sorry if I was unclear. I meant comments that can have more code
after them on the same line.
 
R

reuben doetsch

[Note: parts of this message were removed to make it a legal post.]

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?
 
J

Jeremy McAnally

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

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.



--
http://jeremymcanally.com/
http://entp.com/
http://omgbloglol.com

My books:
http://manning.com/mcanally/
http://humblelittlerubybook.com/ (FREE!)
 
M

Mike Schwab

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!
 
T

Tim Hunter

Mike said:
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.
 
T

Tim Hunter

reuben said:
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?
 
M

Mike Schwab

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.
 
M

Michael W. Ryder

Mike said:
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 */.
 
P

Peña, Botp

RnJvbTogTWljaGFlbCBXLiBSeWRlciBbbWFpbHRvOl9td3J5ZGVyQHdvcmxkbmV0LmF0dC5uZXRd
IA0KIyBUaGUgYmVzdCB3YXkgdG8gcHJvdmlkZSBpbi1saW5lIGRvY3VtZW50YXRpb24gaXMgdG8g
dXNlIG5hbWVzIHRoYXQgDQojIGRvY3VtZW50IHdoYXQgeW91IGFyZSBkb2luZy4gIEluc3RlYWQg
b2Ygd3JpdGluZyB4ICs9IHksIHdyaXRpbmc6IA0KIyB0b3RhbF9iaWxsID0gdG90YWxfYmlsbCAr
IGxpbmVfY2hhcmdlIHdvdWxkIG1ha2UgaXQgZmFyIA0KIyBlYXNpZXIgdG8gZmluZCBhIHByb2Js
ZW0gd2hlbiB0aGUgZmlndXJlcyB3ZXJlIHdyb25nLiAgDQoNCmluZGVlZC4NCg0Kb24gbXkgY2Fz
ZSwgaSB3YW50IHNpbXBsZSB2YXJzLCBzbywNCg0KPGNvZGU+DQoNCiMgYWRkIGxpbmUgY2hhcmdl
cyB0byB0b3RhbCB0DQp0ICs9IGMxICsgYzIgKyBtaXNjDQoNCjxvcj4NCg0KdCArPSBjMSArIGMy
ICsgbWlzYyAgIyBhZGQgbGluZSBjaGFyZ2VzIHRvIHRvdGFsIHQNCg0KPG9yPg0KDQojIHRvdGFs
IGNoYXJnZXMgdCBlcXVhbHMNCnQgKz0gYzEgKyAgIyBsaW5lIGNoYXJnZSAxIHBsdXMNCiAgICAg
YzIgKyAgIyBsaW5lIGNoYXJnZSAyIHBsdXMNCiAgICAgbWlzYyAgIyBtaXNjZWxsYW5lb3VzDQoN
CjwvY29kZT4NCg0Kbm9uZXRoZWxlc3MsIHN0eWxlIGlzIGluIHRoZSBleWUgb2YgdGhlIGJlaG9s
ZGVyIDspDQoNCiMgSSB0aGluayBpdCBpcyBtdWNoIGNsZWFyZXIgdGhhbiANCiMgdXNpbmcgc29t
ZXRoaW5nIGxpa2U6IHggLyogdG90YWwgYmlsbCBhbW91bnQgKi8gKz0geSAvKiBsaW5lIA0KIyBj
aGFyZ2UgKi8uDQoNCm91Y2gsIHRoYXQgaXMgdG9vIG11Y2guIElzIHRoYXQgYSByZWdleCBvciB3
aGF0PyA6KQ0KDQpLaW5kIHJlZ2FyZHMgLWJvdHANCg==
 
J

Jeremy McAnally

total_charges =3D line_charge_1 + line_charge_2 + misc_charges

No comments needed...?

--Jeremy

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 +=3D y, writing:
# total_bill =3D 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 +=3D c1 + c2 + misc

<or>

t +=3D c1 + c2 + misc # add line charges to total t

<or>

# total charges t equals
t +=3D 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 */ +=3D y /* line
# charge */.

ouch, that is too much. Is that a regex or what? :)

Kind regards -botp



--=20
http://jeremymcanally.com/
http://entp.com/
http://omgbloglol.com

My books:
http://manning.com/mcanally/
http://humblelittlerubybook.com/ (FREE!)
 
M

Michael W. Ryder

Peña said:
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,

<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.
 
A

Avdi Grimm

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
 
P

Peña, Botp

From: Jeremy McAnally [mailto:[email protected]]=20
#=20
# total_charges =3D line_charge_1 + line_charge_2 + misc_charges
#=20
# 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 +=3D c1 + c2 + misc

or this,

# add line charges to total
def total
charge.first + charge.last + charge.misc
end

=20
again, it's just style.

kind regards -botp
 
A

Avdi Grimm

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 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.

--=20
Avdi

Home: http://avdi.org
Developer Blog: http://avdi.org/devblog/
Twitter: http://twitter.com/avdi
Journal: http://avdi.livejournal.com
 
M

M. Edward (Ed) Borasky

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
 
P

Peña, Botp

From: (e-mail address removed) [mailto:[email protected]] On=20
# 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..=20

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
 

Ask a Question

Want to reply to this thread or ask your own question?

You'll need to choose a username for the site, which only take a couple of moments. After that, you can post your question and our members will help you out.

Ask a Question

Members online

No members online now.

Forum statistics

Threads
473,769
Messages
2,569,581
Members
45,056
Latest member
GlycogenSupporthealth

Latest Threads

Top