[pacman-dev] Useless comments...

[Bryan Ischo]

Allan McRae wrote:
> Hi,

Hi.  I think much of the problem you are perceiving comes down to a 
difference in comment philosophy between people.  I also got significant 
push back on comments in my changes to the pacman source code and to be 
honest, it surprised me.

For some complex operations, typically encompassed by a single function, 
as in the libalpm _resolve_deps function and similar places, when I 
write such code, I often like my comments to be a "parallel stream" 
describing the steps involved in solving the problem.  Sometimes this 
makes the comments seem obvious because they're explaining what the code 
they immediately precede is clearly doing.  But for me, I like to be 
able to ignore the code and read through the comments in sequence to get 
a general overview of the structure of the code.  Then I like to ignore 
the comments and read the code to see how it's actually implemented.  
This means some necessary redundancy between "obvious comments" and the 
code that it is commenting on.

Some people might suggest that such comments are best in the function 
header comment, and to some people, that may be true.  I like function 
header comments to be more descriptive of the purpose of the function 
than details of its implementation, however.

Also, it helps alot that my emacs coloring scheme puts comments in a 
darker color than code (code is always bright white for me, with some 
keywords highlighted in other bright colors, and comments are always 
sort of a washed-out blue-grey, and don't stand out so much on my dark 
background), so it's pretty easy for me to ignore them.  My eyes seem to 
be able to easily and naturally skip to either comments or code 
depending on which I want to see; I'm not sure how much of this is due 
to the color scheme, and how much is due to years of practice reading 
code this way, but I'm pretty much never annoyed by "useless comments" 
because I just don't read them, except when I want to.

My biggest pet peeve with code is when it is under-commented and messy.  
Because 90% of developers tend to skip comments whenever they can get 
away with it, I never discourage comments, even when they seem useless 
to me.  Useless comments can always be removed pretty easily, because 
it's a simple keystroke to blow them away, but adding comments to 
uncommented code takes actual work.  It would be great if everyone could 
comment their code perfectly, but given the unattainability of this 
goal, I'd rather that people err on the side of too many comments, than 
too few.

That's how I see it, anyway.
Bryan