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 13 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. As Norm Schryer, a researcher at AT&T, so wonderfully said: "If the code and the comments disagree, then both are probably wrong."

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 method 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 method

• 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, author of the seminal The Art of Computer Programming series of books, 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 Chapter 32, "Self-Documenting Code," of Steve McConnell's phenomenal book, Code Complete, 2nd Edition (Microsoft Press, 2005). I learned to write comments by reading this chapter. If you comment correctly, even if your maintenance programmer turns out to be a psychopath, you know you'll be safe.

Some of you may be questioning the earlier line in which I say that you need to document each exception directly thrown by the method. As I discussed back in the "Custom Code Analysis Rules" section in Chapter 2, the exceptions that are directly thrown by the method are the ones that the programmer is much more interested in handling. If you start documenting every possible exception value that can be thrown by every method your code calls, you'll end up listing every exception in the entire Framework Class Library (FCL). It's reasonable to document an exception thrown by a private helper method for a public method because that's just common sense code separation. However, documenting exceptions that can be thrown deep inside the FCL will just confuse all the users of your API.

Since I'm discussing comments, I need to mention how much I love the XML documentation comments, especially now that they are supported by all languages from Microsoft. The main reason is that those XML files produced by the compiler are what's used to build your Intellisense. That alone should be reason enough to produce them religiously.

You can read the help documentation for the specifics, but as I pointed out in Chapter 2, the <exception> tag is one of the most important but one that everyone forgets. That's why I wrote the Code Analysis rule to flag errors when you're not using it. Another tag that everyone forgets is the <permission> tag, with which you can document the permissions you demand for your code to run.

I like the XML documentation comments so much, I built a moderately complicated macro, CommenTater, in Chapter 7 Extending the Visual Studio IDE, that takes care of adding and keeping your XML documentation comments current in addition to ensuring that you're adding them. Although my macro is useful, Roland Weigelt's outstanding GhostDoc add-in (http://www.roland-weigelt.de/ghostdoc/) is what you really want. It's one of those tools that you'll wonder how you can live without.

For example, I had a method called Initialize, which took a path string. Right-clicking the method and selecting Document This from the menu automatically filled in the following documentation:

/// <summary> /// Initializes the specified path. /// </summary> /// <param name="path">The path.</param> void Initialize ( String path ) {     ... }

The beauty of GhostDoc is that it has some serious smarts built in and does an excellent job of figuring out what a big chunk of text should be. You can also add your own rules and analysis in the configuration. It can greatly cut down on a huge chunk of tedious typing for all those simple methods.

The part of GhostDoc that will make you say Whoa! is when you ask it to document an inherited method that you're overloading. It automatically pulls in the base class's documentation, thus saving you a huge amount of time. Of course, it is still your job to ensure that the documentation is the best possible, but I'm all in favor of any helping hand to speed up the process.

Once you have that excellent XML documentation file being produced by the compiler, you'll want to turn to using it to produce your documentation. In the .NET 1.x days, we all used the open source NDOC program, but alas, NDOC is no more. Fortunately, Microsoft is, at the time I write this, working on releasing their internal tool to produce help files, SandCastle. The tool looks very promising and is actively under development. You can find more information on SandCastle at www.sandcastledocs.com. A Community Technical Preview (CTP) was available at the time I wrote this, but SandCastle was undergoing quite a bit of change so I wasn't able to use it in time for the book's release. As soon as SandCastle releases, I will integrated it into the book's source code to produce appropriate help files and release the changes.

If you are serious about producing help files from your XML documentation comments, you'll need to turn to a nice product from Innovasys, Document! X (http://www.innovasys.com/products/documentx.asp). It will not only produce help that makes it easy to integrate that help into the Visual Studio Help system, Innovasys will give you the Dynamic Help capability free. Its integration the IDE is excellent, so you can edit your comments in a WYSIWYG editor so you'll know exactly what the output will look like. Additionally, Document! X supports documenting databases, XSD Schemas, and other code documentation.