[pacman-dev] Useless comments...
bji-keyword-pacman.3644cb at www.ischo.com
Sun Mar 8 19:56:11 EDT 2009
Allan McRae wrote:
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
That's how I see it, anyway.
More information about the pacman-dev