Frank Mitchell

Bad code monkey, no caffeine!

Version control is not a substitute for documentation

“Oh, you don’t need to put comments in. We have version control, and that lets us see exactly what gets changed and when. Besides, good code should be self documenting.”

Pardon me while I get the blunt stick of beating.

The above comment came from a fellow who was working on project with twelve other engineers. That project was somewhere in the neighborhood of 3,000,000 lines of code long. You know what the biggest complaint from the engineers was?

“The code is a nightmare. It’s so hard to understand what’s going on.”

Good documentation eliminates that kind of frustration. Here’s my personal definition of good documentation. I should be able to take a piece of code, remove everything but the comments, and still know exactly what it does, how to use it, and what kinds of errors it might generate. At the very least, every function should have the following:

Documentation means that I don’t have to read a hundred lines of code for a member function to know that it modifies the data in the array I pass into it. Version control won’t tell me that. Documentation means that I can jump right in where I left off three months ago, and know exactly what the intern was thinking when he broke my code. Version control doesn’t let you see people’s ideas. While documentation may take a little more time in the beginning, it saves months of desing, debugging, and testing in the end.

For the curious, the title is a reference to Ernest Adams' Bad Game Designer, No Twinkie! article.