The Value of Commenting Code

Never Changing Constants

Our legacy product started life about 10 years ago, about a year ago before I started here. Not including “designer” generated stuff, the entire code base is about 500,000 lines of VB6 code, spread across 35 projects. Considering that those of us who worked on the project from the beginning did not have much combined experience making a Windows application of this size and scope, you can imagine that a lot of mistakes were made. I don’t think there is anything in the code base today that is worthy of The Daily WTF, but that wasn’t always the case.

I’ve seen many things in the code that made me laugh, cringe, or cry, but my favorite is probably this comment:

	'Never changing constants.
	Public Const AUTO_ID_NAME As String = "RecordID"

I guess the commenter wanted to distinguish the above from those constants that do change...

What Is Your Opinion about Code Comments?

I remember being asked about code comments in my interview to work here.

Interviewer: What is your opinion about code comments?

Me: Uh…they’re good?

I guess that’s what they wanted to hear. Since then my thinking around code commenting has become a lot more nuanced. I’ll summarize it this way:

• Good comments are good.
• Pointless comments are bad.
• Bad comments are worse.
• Most comments (in my experience) are not “good”.

It makes me wonder: What would have been the interviewer’s opinion of my nuanced answer?

At Least It Has Comments

I recently came across this post on The Daily WTF. Here’s the reader’s digest version: The code has been thoroughly commented, but the comments are pretty much the code translated to English. Helpful, I suppose, if you’re not familiar with the programming language being used. Oh well, we’ve all seen worse. Then I starting reading the comments (the comments responding to the post, not the code comments). There was this one:

“H*ll, at least it has comments...”

And this one:

“More comments the better, even if they are "obvious" ones.”

And a bunch more along the same lines. This was very enlightening for me. Apparently trying to write good comments about the intent of the code has been a waste of my time. I’m going to start littering my code with personal anecdotes in the comments. No…even better, I’m going to create a “Comment-ifier” that will automatically improve code quality through randomly generated comments. Patent pending, so don’t even think about it.

The Problem with the Software Development Industry…

I see a link between this attitude about code comments and the recent kerfuffle about some heretical statements uttered by a one Joel Spolsky on Hanselminutes. From the sounds of things, Joel doesn’t think much of the SOLID principles. Gallingly, Joel’s cohort, Jeff Atwood was right there to lend Joel some moral support.

I’m not ready to get on Jeff and Joel’s bandwagon (I do not wish to be excommunicated), but I think they have a point. Programmers Human beings have a strong tendency to latch on to Ideas to make themselves a better programmer human being. I put this down to intellectual laziness. Being better at anything requires continuous effort. Ideas are much easier to implement.

Learning coding “best practices” will (hopefully) make you a better coder, but that is not the key to being a good coder. For one thing, I think it is vital to understand the “why” of those “best practices”. Thinking back to that WTF post, maybe if the person who wrote that code had ever thought about why commented code is important, he or she would’ve come up with some better comments.

The Secret to Good Code

So there are probably at least as many coding “best practices” or methodologies out there as there are fad diets. Do any of them work? All the time? Everywhere? Obviously not, otherwise why are we still talking about it. For what it’s worth, here’s what’s been working for me so far:

1. Care
2. Cheat

Care means care about the quality of your code. Care about the next guy who has to use or maintain what you did. Care about whether your code still works after you’ve retired. Care about your future self, who will probably have to do the same thing again in a different project.

Cheat means copy from the smart kids. Someone somewhere has succeeded at doing something very similar to what you’re working on right now. You just need to find it and copy it as best you can. Of course, to be a good cheat, you’ll need to get your eyes on as much good code or concepts as you can. Even if you don’t need it today, you may at some point in the future. A case in point: One of my all-time favorite books in my library is Writing Compilers and Interpreters by Ronald Mak. I read* it so much, the book is now literally in pieces. Have I ever written a compiler or interpreter? No. Have the techniques outlined in the book helped me with other tasks? Absolutely yes, from simple things like how to properly handle CSV formats with embedded quotes to bigger ideas like how to take a relatively massive problem and break it down into manageable pieces.

Honestly, I don’t think I can say enough about the value of being exposed to as many programming languages, frameworks, architectures, or projects as possible. This is good because:

1. You have a much better chance of knowing the right tool for the job.
2. Seeing the same problem solved in multiple different ways will expand your mind.
3. All those ideas bouncing around in your brain will eventually collide and stick together to make new ideas (not all of them will be good, of course).

* “read” here is intended as past tense. Don’t you just love the English language?