Image: scyther5, Getty Images/iStockphoto

Should you add comments to your code or not? The answer, of course, is yes. It’s also no. Or, less facetiously, “You should first strive to make your code as simple as possible to understand without relying on comments as a crutch. Only at the point where the code cannot be made easier to understand should you begin to add comments.” Jeff Atwood penned that back in 2006, but it’s as relevant today as it was back then. Perhaps more so.

SEE: How to build a successful developer career (free PDF) (TechRepublic)

The case against comments

Bring up the topic and invariably (and soon) someone will tell you why you shouldn’t clutter your code with comments. One of the primary complaints about comments is that they add noise to the code’s signal. “Good code is self-documenting,” the saying goes, and adding comments can sometimes serve to mask bad code, and not for the better. As Bennett Garner has written:

Over-commented code is often more difficult to understand than code without comments. Little notes back and forth from all the different maintainers of a project can often get cluttered. You spend more time reading the comments than you do the actual code. And often, you could have understood how the program works without the comments altogether.

This is bad enough, but the problem compounds as comments age. As Marco Bresciani has argued, “Don’t believe in comments: they’re never updated. Only the code tells the truth.” Comments may have been useful at some point, but as code changes (and that’s common), the comments often don’t. This leaves the code cluttered with outdated comments that could end up confusing rather than clarifying.” Ideally developers would update their comments when updating the code, but this tends not to happen.

Of course, most code editors support code folding, which hides the comments and allows developers to just look at the source code. But this assumes comments are always bad, which isn’t true. When might they be warranted?

The case for comments

Try as much as you might to make your code “self-documenting,” one thing code can’t do: Explain the why behind the code. As Jef Raskin has noted, “[T]he fundamental reason code cannot ever be self-documenting and automatic documentation generators can’t create what is needed is that they can’t explain why the program is being written, and the rationale for choosing this or that method. They cannot discuss the reasons certain alternative approaches were taken.” You might, for example, need to explain why a non-intuitive path was taken, as Bill Sourour calls out, thereby saving future developers the bother of the more obvious (but wrong) approach.

Again, the primary emphasis should be to write high-quality, concise code that (more or less) explains itself. Where this isn’t possible (and it’s not always possible), “Think of comments as the icing on the cake, that exist to provide the reader with information that can’t easily be expressed by the code itself,” to use Brian Hannaway’s words.

Importantly, he continues, it’s critical to keep your audience in mind. It’s a bad assumption to think that those who come upon your code later will have the same level of expertise. As such, he has suggested, cater to the less experienced:

[Y]ou should make your comments accessible and useful to as broad a range of readers as possible. If you’re an experienced tech lead with strong domain knowledge, you shouldn’t comment on your code assuming that the [person] coming behind you will know as much as you do. Instead, write your comments with less experienced developers in mind.

In sum, there are great reasons to keep comments to a minimum, but they don’t obviate the need for comments altogether. You need subsequent developers to be able to understand your code: That starts with writing clean, concise code, but ends with just enough commentary to help them understand why you did things a certain way.