From: "Michael W. Ryder" <_mwryder@...>
Date: 2008-07-25T11:04:13+09:00
Subject: Re: inline comments in future release?

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.