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

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