When are comments "too much", and when are they not enough?

Question

There is an on-going minor debate where I work about the efficacy of comments within code. One of the leads instructed his developers not to use comments as they are too "old fashioned", and a couple of other developers indicated that they never use comments because they feel all they do is clutter up the code.

I have always pretty much adhered to the practice that I comment the top of every file with a basic comment block, comment each method/class/etc definition, and then I comment any place in the code where I think I might come back in 6 months and think to myself, "WTF".

Clearly this is subjective, but I'm curious to know if anyone has any really good arguments or experiences for one way or the other.

Answer 1

This has been discussed to death.

I'll just point you to Jeff Atwood's wonderful post on the subject, which hits the nail right on the head.

Answer 2

Every once in a while I run across code that is so elegantly partitioned, has such compellingly obvious method, field and variable names that everything I need to know is obvious from the code.

In the general case, only really great code gurus write such code. The rest of us cobble together something that works.

• If you're a really great code guru, don't bother sullying your divine code with superfluous comments.
• If you barely know what you're doing, be careful to document your blundering attempts so others can try to salvage the mess.
• If you're average (and most of us are, sort of by definition) then leave some hints in comments for yourself and others to make things easier at maintenance time, but don't insult anyone's intelligence and waste space by documenting the REALLY obvious. Ideally, your comments should describe your code at a meta-level, indicating not what you're doing but why. Also how, if you're doing something unusual or tricky.

Answer 3

The problem with comments is that they tend to stay long after the code that was commented has changed or even been deleted.

As a rule of thumb I'd only comment public API and difficult to understand algorithms.

Don't use comments to explain what you did - that's what the code is for, use comments to explain why you did it.

Answer 4

One should write comment before the code or before the function so that next time looking at the function he/she can know immediately what was the purpose of that code.
It is happened to me many times that I write the code and then forgot the purpose of that. so, I make habit of writing comment before code.

Answer 5

What I'd like to see in the comments is an explanation why a method that is obvious and much simpler than the method used in the code doesn't work.

Answer 6

In all my career, I have never come across that wonderful beast "self-documenting code". Maybe I've just been unlucky, but I'm beginning to suspect it doesn't actually exist.

Answer 7

"One of the leads instructed his developers not to use comments as they are too "old fashioned", and a couple of other developers indicated that they never use comments because they feel all they do is clutter up the code."

If I ever heard a developer I was working with talk like this, I would correct them. If I didn't have the necessary rank to correct them, I would leave the job.

Very clearly written code, with good identifiers -- the stuff sometimes referred to as 'self-documenting' -- does a fine job of illustrating what the code is doing. That's fine as far as it goes. The job of the comments is to explain why.

Answer 8

This topic tends to be discussed a lot, but here are my US$0.02 on the subject:

1. I would rather see too many comments than not enough. Failing at anything, you can always delete superfluous comments from the code; however, you can not derive meaning from them if there are none there to begin with.
2. I've heard some developers argue that other developers that "over document" (definitions of this vary by person) their code are not good developers. While saying that you are updating a counter might be a sign that you don't know what you are doing, having a clear guide to some of the business logic sitting there in the middle of the method you are working on can be quite useful.
3. While there are some excellent developers out there that can write extremely clear code that doesn't require comments, most developers aren't that good or they spend more time writing the code to be self documenting than they would if they had just included a couple comments.
4. You don't know the skill level of the next person to read your code and if the language constructs you are using might be confusing it is usually a good idea to include a comment that someone can use to Google a tutorial with.

Answer 9

Diomidis Spinellis just wrote a nice column for IEEE column (quoted on his blog), outlining the problem, and a few solutions:

When commenting, we’re always a couple of keystrokes away from disaster: restating the code’s function in English. And that’s when problems start.