Comment, Comment, Comment, and Comment

One day, my friend Fran ois Poulin, who was working full-time on maintaining some code that someone else wrote, came in wearing a button that said, "Code as if whoever maintains your code is a violent psychopath who knows where you live." Fran ois is by no means a psychopath, but he did have a very good point. Although you might think your code is the model of clarity and completely obvious, without descriptive comments it is as bad as raw assembly language to the maintenance developers. The irony is that the maintenance developer for your code can easily turn out to be you! Not too long before I started writing the second edition of this book, I received an e-mail message from a company I had worked for nearly 10 years ago asking me whether I could update a project I had written for them. It was an amazing experience to look at code I wrote that long ago! I was also amazed at how bad my commenting was. Remember Fran ois's button every time you write a line of code.

Our job as engineers is twofold: develop a solution for the user, and make that solution maintainable for the future. The only way to make your code maintainable is to comment it. By "comment it," I don't mean simply writing comments that duplicate what the code is doing; I mean documenting your assumptions, your approach, and your reasons for choosing the approach you did. You also need to keep your comments coordinated with the code. Normally mild-mannered maintenance programmers can turn into raving lunatics when they're trying to update code that does something different from what the comments say it's supposed to do.

I use the following approach to commenting:

• Each function or method needs a sentence or two that clarifies the following information:

  • What the routine does

  • What assumptions the routine makes

  • What each input parameter is expected to contain

  • What each output parameter is expected to contain on success and failure

  • Each possible return value

  • Each exception directly thrown by the function

• Each part of the function that isn't completely obvious from the code needs a sentence or two that explains what it's doing.

• Any interesting algorithm deserves a complete description.

• Any nontrivial bugs you've fixed in the code need to be commented with the bug number and a description of what you fixed.

• Well-placed trace statements, assertions, and good naming conventions can also serve as good comments and provide excellent context to the code.

• Comment as if you were going to be the one maintaining the code in five years.

• Avoid keeping dead code commented out in source modules whenever possible. It's never really clear to other developers whether the commented-out code was meant to be removed permanently or removed only temporarily for testing. Your version control system is there to help you revert to areas of code that no longer exist in current versions.

• If you find yourself saying, "This is a big hack" or "This is really tricky stuff," you probably need to rewrite the function instead of commenting it.

Proper and complete documentation in the code marks the difference between a serious, professional developer and someone who is playing at it. Donald Knuth once observed that you should be able to read a well-written program just as you read a well-written book. Although I don't see myself curling up by the fire with a copy of the TeX source code, I strongly agree with Dr. Knuth's sentiment.

I recommend that you study "Self-Documenting Code," Chapter 19 of Steve McConnell's phenomenal book Code Complete (Microsoft Press, 1993). Reading this chapter is how I learned to write comments. If you comment correctly, even if your maintenance programmer turns out to be a psychopath, you know you'll be safe.

Since I'm discussing comments, I need to mention how much I love the XML documentation comments added to C# and how it's criminal that they aren't supported by all the other languages produced by Microsoft. Hopefully, in the future all languages will get the first-class XML documentation comments. By having a clean commenting format that can be extracted during the build, you can start building solid documentation for your project. In fact, I like the XML documentation comments so much, I built a moderately complicated macro, CommenTater, in Chapter 9, that takes care of adding and keeping your XML documentation comments current as well as ensuring that you're adding them.