I had a discussion with a client and a colleague yesterday about commenting code. I haven’t thought about this much lately because most of the code I’ve written in the last few years is, in practice, basically never touched by anyone else. I still prefer that type of work compartmentalization, but won’t be the way it goes in this project, so I’m led to ponder my commenting style.

In a couple words, my commenting style is ‘not much’. However, this is a defensible position :-).

Part of the defense is that when I hear the word ‘comment’, I think about, specifically, little bits interspersed through the code that explain what the lines around are doing. This is different than documentation, which are the bits prefacing each function that explain what the function is for, how to use it, and caveats. Documentation, I’m down with dat.

Speaking, though, of caveats, that is one place where I make sure to add comments. If I know that, say, a section of code makes sub-optimal assumptions about its environment, I mark that fact, and use a ‘TODO: ‘ string to make sure it stands out (today’s IDEs have an automatic feature to extract and display TODOs). Or if I do something that’s nasty, I give it a ‘HACK: ‘. (I do not, however, use ‘TOXIC: ‘, because I associate that with unpleasant memories from a previous work environment. However, you don’t care to know that.)

Beyond caveats, I add comments if I do something that’s so utterly cool and astounding that it’s worth a patent, even if I’m too lazy to patent it. However, this never occurs. If I can write the code, I’m sure you can read its intent. OK, not quite ‘never’… Sometime I do have pretty novel coding ideas.

The biggest problem with comments is that they can get out of sync, since they are not automatically semantically checked against the code they apply to. So I prefer to use features that _are_ semantically checked, in some sense, by the compiler or other tools in the chain. So variable names, for example: if a variable is named ‘isRequired’ and you write ‘if (isProhibited)’, which may be a reasonable thing in your mind at the time, the compiler will tell you there is no such variable and you’ll find your mistake. Other examples are modifiers like ‘const’ and ‘abstract’, assertions, etc. So if I can find a way to express my beliefs in those modes, I do that and skip the commenting.

Thinking about this has me in a sort of mood that I want to think of my code as telling a story. Of course, I’m telling a story to the computer, but the computer is both too dumb and too precise for that same story to make sense to a human. So if I keep my human audience’s cognition in mind in parallel with the compiler’s computation, I can use the syntactic richness of the language elements to tell the story simulataneously to both audiences. The computer doesn’t care about the difference between ‘InsufficientUserIntelligenceException’ and ‘N13B’, but a fellow coder will.