November 2014

S M T W T F S
      1
234567 8
9101112131415
16171819202122
23242526272829
30      

Style Credit

Expand Cut Tags

No cut tags
Friday, October 3rd, 2014 10:46 am
[Cross-posted from the Vision Riders Blog. You are welcome to comment here or there.]

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.

(Emphasis mine.)

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:

Well-commented C++ code.

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.

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

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

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

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

Reply

From:
Anonymous( )Anonymous This account has disabled anonymous posting.
OpenID( )OpenID You can comment on this post while signed in with an account from many other sites, once you have confirmed your email address. Sign in using OpenID.
User
Account name:
Password:
If you don't have an account you can create one now.
Subject:
HTML doesn't work in the subject.

Message:

 
Notice: This account is set to log the IP addresses of everyone who comments.
Links will be displayed as unclickable URLs to help prevent spam.