Code documentation should include high- and low-level design documents that you can store in the document repository with other kinds of documentation. These provide an overview of the methods the code is using to do whatever it’s supposed to do.
Code documentation should also include comments in the code to help you understand what the code is actually doing and how it works. You don’t need to comment every line of code (see the numInvoicesLost example again), but it should provide a fairly detailed explanation that even the summer intern who was hired only because he’s the boss’s nephew can understand. Debugging code should be an exercise in understanding the code and figuring out why it isn’t doing what it’s supposed to do. It shouldn’t be an IQ test.
JBGE
There’s a school of thought in software engineering that says you should provide code documentation and comments that are “just barely good enough” (JBGE). The idea is that if you provide too much documentation, you end up wasting a lot of time updating it as you make changes to the code.
This philosophy can reduce the amount of documentation you produce, but it’s an idea that’s easy to take too far. Most programmers like to program (that’s why they’re not lawyers or doctors) and writing and updating documentation and comments doesn’t feel like writing code, so sometimes they skip it entirely.
A software engineering joke says, “Real programmers don’t comment their code. If it was hard to write, it should be hard to understand and harder to modify.” Unfortunately I’ve seen plenty of code that proves the connection between poor documentation and difficult modification.
I worked on one project that included more than 55,000 lines of code and fewer than 300 comments. (I wrote a program to count them.) And if there were design documents, I never heard about them. I’m sure the code made sense when it was written, but modifying it was next to impossible. I sometimes spent 4 or 5 days studying the code, trying to figure out how it worked before changing one or two lines. Even after all that time, there was a decent chance I misunderstood something and the change added a new bug. Then I got to remove the change and start over.
I worked on another project that included tons of comments. Probably more than 80 percent of the lines of code included a comment. They were easy to ignore most of the time, but they were always there if you needed them.
After we transferred the project to the company’s maintenance organization, the folks in the organization went on a JBGE bender and removed every comment that they felt wasn’t absolutely necessary to understand the code. A few months later, they admitted that they couldn’t maintain the code because – …drumroll… – they couldn’t understand it. In the end, they put all the comments back and just ignored them when they didn’t need them.
Yes, excessive code documentation and comments are a hassle and slow you down, so you can’t rush off to the next task, but suck it up and write it down while it’s still fresh in your mind. You don’t need to constantly update your comments every time you change a line of code. Wait until you finish writing and testing a chunk of code. Then write it up and move on with a clear conscience. Comments may slow you down a bit, but I’ve never seen a project fail because it contained too many comments.
JBGE, REDUX
JBGE is mostly applied to code documentation and comments, but you could apply the same rule to any kind of documentation. For example, you could write barely enough documentation to explain the requirements. That’s probably an even bigger mistake than skimping on code comments.
Documentation helps keep the whole project team working toward the same goals. If you don’t spell things out unambiguously, developers will start working at cross-purposes. At best you’ll lose a lot of time arguing about what the requirements mean. At worst you’ll face a civil war that will destroy your team.
As is the case with code documentation and comments, you don’t need to turn the requirements into a 1,200-page novel. However, if the requirements are ambiguous or confusing, pull out your thesaurus and clarify them.
JBGE is okay as long as you make sure your documentation actually is GE.
You can extend the JBGE idea even further and create designs that are just barely good enough, write code that’s just barely good enough, and perform tests that are just barely good enough. I’m a big fan of avoiding unnecessary work, but if everything you do is just barely good enough, the result probably won’t be anywhere near good enough. (Not surprisingly, no one advocates that approach. The JBGE philosophy seems to be reserved only for code comments.)
Some programming languages provide a special kind of comment that is intended to be pulled out automatically and used in text documentation. For example, the following shows a snippet of C# code with XML comments:
The comment’s summary token explains the method’s purpose. The param tokens describe the method’s parameters. The Visual Studio development environment can automatically extract these comments into an XML file that you can then process to produce documentation. The result doesn’t explain how the code works, but if you do a good job writing the comments, it does explain the interface that the method displays to other pieces of code. (Visual Studio also uses these comments to provide help pop-ups called IntelliSense to other developers who call this code.)
As is the case when you write code documentation and other comments, you don’t need to constantly update this kind of information as you work on a method. Finish the method, test it, and then write the comments once.
APPLICATION DOCUMENTATION
All the documentation described so far deals with building the application. It includes such items as requirements and design documents, code documentation and comments, meeting and phone call notes, and memos.
At some point you also need to prepare documentation that describes the application. Depending on the eventual number and kinds of users, you may need to write user manuals (for end users, managers, database administrators, and more), quick start guides, cheat sheets, user interface maps, training materials, and marketing materials. You may even need to write meta-training materials to teach the trainers how to train the end users. (No kidding, I’ve done it.)
In addition to basic printed versions, you may need to produce Internet, screencast, video, and multimedia versions of some of those documents. Producing this kind of documentation isn’t all that different from producing requirements documents. You can still store documents in an archive. (Although you may not be able to search for keywords in a video.)
Although creating this material is just another task, don’t start too late in the project schedule. If you wait until the last minute to start writing training materials, then the users won’t be able to use the application when it’s ready. (I remember one project where the requirements and user interface kept changing right up until the last minute. It was somewhat annoying to the developers, but it practically drove our lead trainer insane.)
SUMMARY
Documentation is produced throughout a project’s lifespan, starting with early discussions of the project’s requirements, extending through design and programming, continuing into training materials, and lasting even beyond the project’s release in the form of comments, bug reports, and change requests. To get the most out of your documentation, you need to set up a document tracking system before you start the project. Then you can effectively use the project documents to determine what you need to do and how you should do it. You can also figure out what was decided in the past so that you don’t need to constantly rehash old decisions.
Document control is one of the first tools you should set up when you’re considering a new project. You can use it to archive ideas before you know