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

Question

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

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.

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.

"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.

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.

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.

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.