Olin Lathrop wrote:

> Vitaliy wrote:
>> - Good names eliminate the need for line-by-line comments
> 
> I think this is our major disagreement.  A good subroutine name, for
> example, can at best explain what the subroutine does.  Only a comment
> can explain why that function is being used right here right now.

It seems to me that you guys are saying the same thing, mostly :)

Vitaliy wrote (in a part you snipped): "I believe that the real purpose of
comments is to provide the context, to explain *why* something is being
done (never *what* is being done)."

Sounds to me pretty much the same. When you talk about "header comments",
that's different from what Vitaliy is talking about in the quote with
"line-by-line comments". The line-by-line comments usually are not about
why, they mostly are about what. In general (note that I wrote here "in
general"! :) good written code doesn't need many line-by-line comments. It
does need occasional short paragraphs that explain the "why" -- and the
minimum of such paragraphs is the function header comment. I don't think
that you're in any disagreement with Vitaliy here.

> But then where do you describe the why as apposed to the what of the
> subroutine call.

In the header comment, which is a line or a short paragraph, but not an
end-of-line comment (or a series of those).

> Comments perform a important function that can't be replaced by any amount
> of clever naming, and therefore have their purpose on most lines.  

I disagree. I have yet to see good code where end-of-line comments are
necessary to understand it. Generally a short paragraph that outlines the
"why" of the next 10 or 20 lines or so, then well-structured code with
meaningful names that make sense in the light of the "why" paragraph does
it pretty nicely. 

> You need to ballance explaining the what with the why.  Clever names can
> only tell you the what at best.

Exactly, and that's their purpose. Done right, there shouldn't be much need
for explaining the "what" in comments.

> Where does this end?  At some point you have to write some real code.

The thing is that I've seen code (and not just a little of it) where the
coder tried hard to do with short names, just to add a whole romance in
comments about what was being done. This is not normally good code. In
general, I find it more useful to write meaningful names and really sparse
comments about the "what". I often even create basically unnecessary
intermediate variables with names that explain what this intermediate value
is, rather than explaining that in a comment. The variable creation (in the
cases where it is really unnecessary) is optimized out by the compiler, so
it doesn't incur any runtime overhead. It just "explains" in code rather
than in comment what is being done.

> Vitaliy, I know you're a smart guy, but I think you've read too many
> books and papers by ivory tower computer science types that have
> forgotten (or maybe never knew) what it was like to get real projects
> done.  

There are different types of projects, and they require different forms of
practices. But I don't think that what Vitaliy was describing is off for
any size project -- it doesn't cost time (it most likely saves time), and
stuff like this helps me getting my projects done. (But then, I don't do
projects in assembly :)

Gerhard

-- 
http://www.piclist.com PIC/SX FAQ & list archive
View/change your membership options at
http://mailman.mit.edu/mailman/listinfo/piclist