Documentation Overkill

2008.04.16   prev     next

In one of the jobs I’ve had in the past several years, my team finished work on a project, and was then told to document it. What did that entail? It meant that we had to create an immense Word file, many hundreds of pages long. This file contained:

• detailed descriptions of every function, every parameter of every function, and the output of every function
• lists of which functions call which other functions
• schematic, flowchart-like diagrams of what every function does
• lists of all files in the project, their locations, and other information about them
• and much more

The most depressing thing about having to make such a document was my certain knowledge that after I was gone, whatever developer took over this project would take one, ten-second look at this enormous document and then just put it aside. And start looking at the code.

Even if your employer requires you to create such voluminous documentation, try to keep in mind that really, your code is its own documentation. When future developers (including yourself?) want to know what functions your project has, they will look at the code. When they want to know what parameters a function has, they’ll look at the code. When they want to know generally what a function does, they’ll look at the comments immediately above that function — in the code. When they want to know precicely what a function does, they’ll look at the code of that function. And when they want to know which functions call function X, they’ll do a five-second, project-wide search for the name of function X, and get their answer faster than they could ever find it by looking it up in an eight-hundred page Word document.

And if a developer can’t discover this kind of information by looking at the code, then it’s pretty much a sure thing that that particular developer shouldn’t be working on this code. Even if he’s armed with an eight-hundred page Word document.

And — need I even mention the possibility of mistakes in that behemoth Word document? No compiler will ever flag them. No testers or users will ever catch them. So even if it took longer to get answers by looking at the code, it would still be a better, safer way to get those answers.