WhyCommentsAreBad

I've been dropping hints here and there on this wiki that I am not a big supporter of heavily commented code. Now, I just decided to clarify it a bit since the my remarks taken by themselves might be mistaken for an unwillingness to document your code. Therefore let me start with telling you that I make a distinction between "code comments" and "code documentation". The former is bad. The latter is good. IMO. But of course things are not always black and white. -- PEZ

Comments to compensate badly factored code

Some people tend to automatically think that the more comments in the code the easier it will be to maintain. I beg to differ. To me a comment behind a line of code or before a block of code most often means the code by itself isn't clear enough. Isn't factored like it could be. Consider this:

...
// Calculate the abosulte bearing to the target:
b = Math.atan2(target.x - bot.x, target.y - bot.y);
...

vs this:

...
absoluteBearing = Math.atan2(target.x - bot.x, target.y - bot.y);
...

or even:

    public double absoluteBearing(Bot target) {
        return Math.atan2(target.getX() - this.x, target.getY() - this.y);
    }

and then you can choose to call that method on your bot wherever you need the bearing instead of storing it in a temp variable.

This is a very simple example. But believe me, I've seen really huge functions/methods that do all sorts of stuff with a comment prepending each block of functionality. Extracting methods is almost always the answer to such overuse of comments. You see an extracted method lends itself to "code documentation". To make more use of the simple example:

    /**
     * Calculates and returns the absolute bearing between this Bot and the target Bot. 
     *
     * @param  target  the target Bot
     * @return         the absolute bearing
     */
    double absoluteBearing(Bot target) {
        return Math.atan2(target.getX() - this.x, target.getY() - this.y);
    }

A rule of thumb is that "if you can think up the comment to prepend to a block of code you probably can think up the name of the extracted method that the block of could should go in".

-- PEZ

Utterly useless comments

Of course there are even sillier comments found in some code. Like:

...
distance1 = ...
distance2 = ...

// sum them up
totDistance = distance1 + distance2;
...

No, I am not kidding. I have seen stuff like that for real! The only place I could think of that sort of comment would fit is in a tutorial teaching how to use sum values up in a given programming language. But even then I would suggest that the author instead of a code comment used typographic clues in the book or webpage or whatever to tell that we're summing things up here. Using a comment risks to teach a bad commenting behaviour as a side effect.

-- PEZ

Another real-world example. This from a book on Python that I'm currently reading. It's a script that counts words in a text file:

    # reset word count
    count = 0

Sigh.... What's wrong with:

    word_count = 0

?

-- PEZ

Feedback

Feel free to add your own sections and examples on when comments are bad (or good, if indeed you can find such an example). -- PEZ

I've been in the habit of using fairly clear (imo) variable and method names for years. Just to be sure I wasn't about to stick my foot in my mouth, I reviewed my published code samples (Ugluk/Code Samples) and they have JavaDoc? but no inline comments (that I noticed). I do like to use comment blocks to delineate collections of things, such as constructors, functional methods, mutators / accessors, and various member field categories. -- Martin

I really like it when there are comments that explain why something works. Because despite having clear variable/method names, it's still sometimes necessary to go and chase down exactly what the method is doing. Comments help when I don't know what the code is supposed to be doing or why. For the longest time, I could read CassiusClay's code and I could see what was happening, but I did not understand what was going on. I think in English, so I have to translate the code in my head anyway, and I don't mind when that's done for me. -- Alcatraz

I like how the "WhyCommentsAreBad" page has a Comments section. --David Alves

Heh, I've fixed that now. =)

As I have missed Alcatraz's input before, let me address that. CassiusClay really lacks documentation in the code. I'm not on a crusade against documentation. Classes and methods and interfaces and what-have-you should be documented. But unless the algorithm of a function performed is tricky there shouldn't be any need to comment the lines of code much if the code is well factored. And, let it be known, CassiusClay is really in need of refactoring too.

-- PEZ

Hey, I agree with you on kmost of it, actually my bots are overall generally lacking in comments of even the method defining variety. But I say if thats how someone wants thier bot to be 90% comment and 10% code, I say let them (however I personally perfer a more 0.1% : 99.9% ratio).

-- Chase-san

Was just bouncing around with the "Random Page" link and clicked on an old link that used to go to David McCoy?'s (of PrairieWolf fame) Survivalist and Perceptual League; now it goes to a page called [The Myth of Self-Documenting Code], which seems relevant to this conversation. Note that he isn't making the direct contrast between comments and documentation that PEZ does above, so I wouldn't necessarily call this the exact opposite of PEZ's philosophy about the two. An interesting read, in any case. -- Voidious

I've missed this piece of feedback. I skimmed the myth-article now. It say about the same thing that I am saying here. But in failing to see the differences between code documentation and code comments it probably ends up misguiding inexperienced programmers. I thinks the rule of thumb should be that if you see a comment you're also looking at a need for refactoring. -- PEZ

While I agree that comments can get ridiculous, there is one reason that I like using them where I otherwise wouldn't: Eclipse. I like hovering over a method or class name and getting a brief description in a tooltip, without having to go and actually open up the class or the javadoc. --RobertWalker

Not just in Eclipse (though it makes very good use of them) but javadoc comments are in a different league... They can be used to generate documentation completely separate from the code... (well, mostly separate). I fear I must sit on the fence on this one. I don't like entering comments, so when things change I don't update them. That makes them bad, and get worse as time passes. But if I can put in a comment here and there and reduce the number of methods in a class by half... I would probably opt for the comments... --BenHorner

For what it's worth, this philosophy clearly makes a distinction between "documentation" and "comments", just as you two both seem to be. I'm pretty sure the idea is that documentation of methods and classes is good, but needing to comment a piece of execution code is probably indicative of code that could be rewritten to be more clear. While Dookious is also sorely lacking a lot of documentation, I kind of used it as an experiment in writing code in a way that required no comments anywhere; I know a few spots aren't quite up to that level, but I think most of it is. -- Voidious

Wow, I have missed this piece of information about Dookious. That's awesome. Bloody awesome. I must go read the Dookious code more thoroughly now. -- PEZ

Heh, I wish I could say the same about DrussGT. I have been putting off that major refactor for a LOOONGGG time now... Dookious's score went up after his refactor... perhaps a refactor for DrussGT would do the same? -- Skilgannon