inline comments in future release?

Discussion in 'Ruby' started by Mike Schwab, Jul 24, 2008.

  1. Mike Schwab

    Mike Schwab Guest

    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/.
    Mike Schwab, Jul 24, 2008
    #1
    1. Advertising

  2. Mike Schwab

    ara.t.howard Guest

    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




    p :you # can do this....


    a @ http://codeforpeople.com/
    --
    we can deny everything, except that we have the possibility of being
    better. simply reflect on that.
    h.h. the 14th dalai lama
    ara.t.howard, Jul 24, 2008
    #2
    1. Advertising

  3. Mike Schwab

    Mike Schwab Guest

    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, Jul 24, 2008
    #3
  4. [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?

    On Thu, Jul 24, 2008 at 4:57 PM, Mike Schwab <> 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/.
    >
    >
    reuben doetsch, Jul 24, 2008
    #4
  5. 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 <> 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 <> 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/
    http://omgbloglol.com

    My books:
    http://manning.com/mcanally/
    http://humblelittlerubybook.com/ (FREE!)
    Jeremy McAnally, Jul 24, 2008
    #5
  6. Mike Schwab

    Mike Schwab Guest

    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/.
    Mike Schwab, Jul 24, 2008
    #6
  7. Mike Schwab

    Tim Hunter Guest

    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/
    Tim Hunter, Jul 24, 2008
    #7
  8. Mike Schwab

    Tim Hunter Guest

    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/
    Tim Hunter, Jul 24, 2008
    #8
  9. Mike Schwab

    Mike Schwab Guest

    > 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/.
    Mike Schwab, Jul 25, 2008
    #9
  10. 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.
    Michael W. Ryder, Jul 25, 2008
    #10
  11. RnJvbTogTWljaGFlbCBXLiBSeWRlciBbbWFpbHRvOl9td3J5ZGVyQHdvcmxkbmV0LmF0dC5uZXRd
    IA0KIyBUaGUgYmVzdCB3YXkgdG8gcHJvdmlkZSBpbi1saW5lIGRvY3VtZW50YXRpb24gaXMgdG8g
    dXNlIG5hbWVzIHRoYXQgDQojIGRvY3VtZW50IHdoYXQgeW91IGFyZSBkb2luZy4gIEluc3RlYWQg
    b2Ygd3JpdGluZyB4ICs9IHksIHdyaXRpbmc6IA0KIyB0b3RhbF9iaWxsID0gdG90YWxfYmlsbCAr
    IGxpbmVfY2hhcmdlIHdvdWxkIG1ha2UgaXQgZmFyIA0KIyBlYXNpZXIgdG8gZmluZCBhIHByb2Js
    ZW0gd2hlbiB0aGUgZmlndXJlcyB3ZXJlIHdyb25nLiAgDQoNCmluZGVlZC4NCg0Kb24gbXkgY2Fz
    ZSwgaSB3YW50IHNpbXBsZSB2YXJzLCBzbywNCg0KPGNvZGU+DQoNCiMgYWRkIGxpbmUgY2hhcmdl
    cyB0byB0b3RhbCB0DQp0ICs9IGMxICsgYzIgKyBtaXNjDQoNCjxvcj4NCg0KdCArPSBjMSArIGMy
    ICsgbWlzYyAgIyBhZGQgbGluZSBjaGFyZ2VzIHRvIHRvdGFsIHQNCg0KPG9yPg0KDQojIHRvdGFs
    IGNoYXJnZXMgdCBlcXVhbHMNCnQgKz0gYzEgKyAgIyBsaW5lIGNoYXJnZSAxIHBsdXMNCiAgICAg
    YzIgKyAgIyBsaW5lIGNoYXJnZSAyIHBsdXMNCiAgICAgbWlzYyAgIyBtaXNjZWxsYW5lb3VzDQoN
    CjwvY29kZT4NCg0Kbm9uZXRoZWxlc3MsIHN0eWxlIGlzIGluIHRoZSBleWUgb2YgdGhlIGJlaG9s
    ZGVyIDspDQoNCiMgSSB0aGluayBpdCBpcyBtdWNoIGNsZWFyZXIgdGhhbiANCiMgdXNpbmcgc29t
    ZXRoaW5nIGxpa2U6IHggLyogdG90YWwgYmlsbCBhbW91bnQgKi8gKz0geSAvKiBsaW5lIA0KIyBj
    aGFyZ2UgKi8uDQoNCm91Y2gsIHRoYXQgaXMgdG9vIG11Y2guIElzIHRoYXQgYSByZWdleCBvciB3
    aGF0PyA6KQ0KDQpLaW5kIHJlZ2FyZHMgLWJvdHANCg==
    Peña, Botp, Jul 25, 2008
    #11
  12. total_charges =3D line_charge_1 + line_charge_2 + misc_charges

    No comments needed...?

    --Jeremy

    On Thu, Jul 24, 2008 at 9:43 PM, Pe=F1a, Botp <> wrot=
    e:
    > From: Michael W. Ryder [mailto:]
    > # 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!)
    Jeremy McAnally, Jul 25, 2008
    #12
  13. Peña wrote:
    > From: Michael W. Ryder [mailto:]
    > # 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
    Michael W. Ryder, Jul 25, 2008
    #13
  14. Mike Schwab

    Avdi Grimm Guest

    On Thu, Jul 24, 2008 at 9:05 PM, Mike Schwab <> 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
    Avdi Grimm, Jul 25, 2008
    #14
  15. Mike Schwab

    Peña, Botp Guest

    From: Jeremy McAnally [mailto:]=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
    Peña, Botp, Jul 25, 2008
    #15
  16. Mike Schwab

    Avdi Grimm Guest

    On Thu, Jul 24, 2008 at 11:22 PM, Pe=F1a, Botp <> wro=
    te:
    > 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
    Avdi Grimm, Jul 25, 2008
    #16
  17. On Fri, 2008-07-25 at 13:02 +0900, Avdi Grimm 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
    M. Edward (Ed) Borasky, Jul 25, 2008
    #17
  18. Mike Schwab

    Avdi Grimm Guest

    Avdi Grimm, Jul 25, 2008
    #18
  19. Mike Schwab

    Avdi Grimm Guest

    Avdi Grimm, Jul 25, 2008
    #19
  20. Mike Schwab

    Peña, Botp Guest

    From: [mailto:] 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
    Peña, Botp, Jul 25, 2008
    #20
    1. Advertising

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

It takes just 2 minutes to sign up (and it's free!). Just click the sign up button to choose a username and then you can ask your own questions on the forum.
Similar Threads
  1. William Rose
    Replies:
    0
    Views:
    467
    William Rose
    Sep 22, 2005
  2. Replies:
    0
    Views:
    1,094
  3. Monk
    Replies:
    10
    Views:
    1,436
    Michael Wojcik
    Apr 20, 2005
  4. Replies:
    1
    Views:
    360
    Daniel Pitts
    Feb 25, 2008
  5. Simon Strandgaard

    [ann] aeditor-2.2 (future release)

    Simon Strandgaard, Jan 23, 2005, in forum: Ruby
    Replies:
    1
    Views:
    86
    Simon Strandgaard
    Jan 23, 2005
Loading...

Share This Page