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