17 Days: On The Benefits Of Comments

For those who aren't software developers, I'll explain the the word code. In the early days of computing, programmers wrote short, cryptic programs that were unreadable by anybody who wasn't highly trained. In fact, even highly trained people had problems reading programs written by other people. This unreadability led to computer programs being code, as if it was "in a code" that required decryption in order to be read.

Flash forward many years and things have changed. We now write long, cryptic programs. But, we still refer to the lines of computer programs as code. Things have improved slightly through the addition of comments. While most computer code is either declarative (specifies something about the program) or procedural (actually does something), comments are notes placed in the code that are intended to be read by a human. They don't do anything -- except make the code clearer.

Like most programmers, I didn't always have good commenting habits. My first large program was 2,000 cards (yes, punch cards) of assembly language with nary a comment. These days, I comment everything -- even when I'm building a one-person startup -- and I don't just comment code. For example, I comment Illustrator and Photoshop files when I'm creating artwork where I might not remember what I did or why.

Not everybody thinks that comments are valuable. I've been told that I shouldn't write comments because it slows down development. The argument is that code should be readable without comments and that it's faster to rewrite it from scratch later if there are problems than to write comments in the first place. Unfortunately, all code -- including my own -- isn't nearly as readable as the authors would like to believe. Sure, good variable naming and other things can help, but they don't substitute for comments explaining what's going on or why the code is written like it is.

Recently, I had a great example of the value of comments. I broke something that had been working before. What happened? There was a slightly complex chunk of logic that seemed to be failing. Fortunately, I had commented the code, so I knew exactly what it was supposed to do without having to remember the details or figure it out from context. When I looked at the comment and the code, it was clear that they didn't agree -- I had inadvertently deleted something while making an unrelated change.

Yes, I could have used the debugger and figured it out, but such bugs of omission are hard to find -- after all, the code that isn't there just isn't there. My comments turned a potential crisis into a 1-minute fix. And, whether you're building a startup in 30 days or you're taking a more leisurely pace, that's a good thing.

Moral of the story: Comment your code, even if it's just for yourself.