Is Coding Sans Comments Always A Mistake?

10 FOR X = 1 TO 10
20   PRINT X
30 NEXT X

This is, more or less, the first code I ever wrote at school. As best I recall, I was required to add comments to it. But there's nothing useful that can be said about it that isn't simply a restatement of the code. Anyone reading the code knows not only what the code does but also why it is doing it. Nor is there anything that can be said about the choices that were made in electing to use that particular code that isn't simply noise.

Code commenting is not win-win. Every comment has a cost to be borne in its initial writing, in its reading and comprehension each time the code is visited, and in its maintenance. The maintenance of comments can be particularly problematic. If the code to which the comment applies (which in many languages is not automatically obvious) is changed, then it dirties the comment and it may become invalid. If it's not then corrected, no unit test will fail, and no QA test will pick it up. (A code review might catch it, but that's very much subject to human failings.) Then confusion can occur as a later maintainer must deal with a comment that makes no sense for the code that it appears attached to, necessitating a careful study of the version history to unpick. It can even lead to developers being unwilling to make a good change to a piece of code for the fear, uncertainty and doubt of the damage they might do.

So commenting code should be considered carefully. If the value of the comment is not greater than the costs involved in its presence, it should not be written. For that reason, I contend that the code at the start of this comment should not be commented.

Comments convert your language to English; they explain to the otherwise uninformed viewer what your code does in a simple fashion that doesn't need a lot of explanation. Personally, I'm a big fan of comments, but it seems like that might only be in theory.

In practice, when I'm coding anything, writing comments is usually not my first impulse. I'm there to write code that does something, and I totally get how it works because I made it - if I didn't understand how my own code worked, I'd have a larger problem. This however becomes quite difficult when multiple people begin working on the codebase, or really when anyone is trying to read and interpret your code.

This is where writing interpretable code comes in. I know a lot of developers who frown on giving things descriptive names, but it's a key piece in the comment liberation process. Take this code for example.

// number of tickets purchased
const a = 5;

const ticketsPurchased = 5;

Can you write the top line if you include the comment? Yes, but it's frowned upon - even with the comment. That variable name is just too vague, and the fact that there happens to be a comment there only improves the code so much. Comments can't save bad code by themselves.

Can you write the bottom line even though it doesn't have a comment? Of course! It's perfectly understandable as to what the variable stands for.

TLDR; Good code comes first. Commenting should always be a last resort for bits of code that just don't make sense logically at first glance. If you're writing a regular program that has more comments than code, you might want to look at writing more readable code. Don't use commenting as an excuse to be sloppy with your code.

There was this neat little web project that consisted of about 80 lengthy php files. Somebody had written the code years ago, but even this somebody was not able to keep the code running. More and more things stopped working over time.

When I checked the files, there where nearly no comments included. No hint, who wrote the code, any date or version number, which php version the code was written for.

In that case, missing comments made our life easier. It was a quick decision to put the code in the dust bin and rebuild everything from scratch.