There’s a lot of programmers out there that are big fans of “self-documenting code”. That is, code that is easily understandable without comment lines explaining it. Robert Martin, in his book Clean Code: A Handbook of Agile Software Craftsmanship, even goes so far as to say:
The proper use of comments is to compensate for our failure to express ourself in code. Note that I used the word failure. I meant it. Comments are always failures. We must have them because we cannot always figure out how to express ourselves without them, but their use is not a cause for celebration.
The philosophy here is “your code should speak for itself”. After all, a programming language is a language, right? We don’t need asides just to get through a block of pure English text, do we?
The thing is, programming languages are not one-to-one equivalents to a human tongue. For that reason I follow a different philosophy, as you can probably tell from this sample of some C++ code I wrote:
Some of you out there who are programmers are probably cringing right now looking at that. Take, for example, the c = file->peek() line at the bottom. Anyone with experience in C++ would recognize at once what I’m doing. Really, anyone familiar with file input/output in general should understand what I’m doing just from the “peek”. I’m looking ahead one character in the file, without advancing the file reader, and storing the value in the character variable named “c”.
Yet despite that, the line is proceeded by a comment: “Peek at the next value.” It describes the obvious. Some would say it’s useless and redundant. But I purposefully took the time to type it out there anyway. As you can probably see, I’ve even done it more than once.
I strongly believe code should be well-formatted, organized, and easy-to-read, but also extensively commented. Why? There’s several reasons.
- It keeps me focused. I type out what I’m trying to do right before I go about it, so I have a good idea how I need to format the code to best accomplish whatever task is at hand. When you look at my comments, you’re not just seeing what I’m doing, you’re seeing the entire thought process behind it.
- It helps me keep my code organized. I can easily skim through the comments to find the chunk of logic I’m looking for, without having to dig too deep into the code itself.
- It makes it easier for me to find mistakes. Occasionally I can spot a bug by just running through the comments and seeing the thought process doesn’t line up. I’m missing a step! Other times, I’ll actually find bugs by seeing that a comment doesn’t match the code that follows it. My implementation is wrong because I goofed and wasn’t following the logic that I’d stepped through in the comments.
- Building on point 1, it reminds me what I was thinking when I wrote the code. A lot of times I’ll wonder, “why did I write it this way?” Then I’ll go back over the comments and remember. It’s saved me rewrites before, especially when I’ve forgotten that I already tried what I might think is the “better” way and realized it won’t do what I need it to.
According to Google’s C++ coding style standards, when writing comments you should “assume that the person reading the code knows [programming] better than you do.” I for one don’t. I assume that the person reading my comments is an idiot. Because I will be reading them later.
I completely agree with you on that one. The code I write is also extensively commented, very similar to yours.
Rather than just writing what a line does, I find it even more important to explain WHY something is done. I often notice that in open source projects. If you write some code that does an action where it isn’t obvious why you did it, then you often have it that later on someone removes the line in the code, breaking a alot of other parts without realizing it. So it just seems reasonable to put some comment there like:
//We have to do that here so that xyz works
Also many comments serve for easier access to information. Like say you have a function and it gets a parameter “flag”. If you add a function comment that explains what each parameter means and what the possible values are you just need to look at the function and know what to do. Otherwise, no matter how easy-to-understand and well-structured the code is, you will need to search for all calls of the function and see at what part what value is given as “flag” just to figure out what those values could mean.
When I work with commented code I’m definitely more than 3 times faster than when I work with completely uncommented code.
Yeah, that’s definitely a big plus for me. As I sort of touched on, I have rewritten parts of my code before to be “better”, only to realize I’d already tried it that way and it doesn’t work.