Dropbear Consulting - For those who follow...documenting your programs

Programmers, especially younger ones, are notoriously resistant to writing any documentation for their code. This is partly about experience and partly about managers ensuring that writing the documentation delivers value to the person writing it, not just to tick some project management requirement.

In this article I'm talking about the internal code documentation of an application, rather than the specifications, user manuals or other project documents.

Why we hate to write documentation

For the programmer, documentation is often seen as a pointless overhead - time better spent programming. While you're working on a programming project, the internal structures and functions are familiar and readily available so you never need any documentation; after you've finished the programming (which is the fun bit), going back over the code to write documentation seems pointless.

Department policies that require program documentation in some bizarre (to the programmer) format, or that mandate fixed formats and rules that are not applicable invite subversion. If your rules make my life hard, I will avoid them.

Why we really, really should

Once you've had to pick up a few projects that other people have left with no documentation you start to learn. The start-up overhead to get a programmer up to speed in a new project or environment is significant (weeks, possibly months, sometimes years...). For every part of the code you have to what it's doing and how it fits into the wider application or environment. This means either:

work it out on your own with trial and error, or
ask another team member (taking them away from their own work)

Good application documentation won’t turn a novice into an export overnight, but it will make liFe easier.

Even an experienced programmer is a novice (for a while) in a new environment or project.

The paths of righteousness

So how can you make it easier to get useful program documentation? There are a few guidelines that I think help.

Separate API documentation from code comments

API documentation covers the classes and methods or functions exposed and used by an application. API documentation needs to be useful to another programmer using your application. It needs to describe the inputs and outputs and expected uses of each method in the program.

Code comments are the internal notes about specific techniques or special variables within each block of code. Comments like these are relevant to a programmer working on your code. It is often as important to document why a bit of code is doing something as it is to document how it's doing it.

Some argue that it's better to put all the documentation for one file of source code together at the end of the file where it's easier to read as a single block and doesn't 'clutter' the code. I generally prefer to have the documentation interspersed with the code, so I can see the documentation (and update it) while I'm working on that bit of the program. So long as it gets done...

Document with the same tools that you use to program

I think most program documentation should be in the source code. Having the documentation in front of you while you program makes it easier, more naturally part of the job, to keep it up to date.

There are situations where you need external tools, but try to keep them to a minimum - if possible use aN automated generator to assemble the different sources of documentation into a single repository.

Accuracy may be more important than completeness

I would rather have 80% of the functions well documented than 100% out of date.

But good comments don't make up for bad code.

Don't talk down to me; don't make me talk down to others

This is about documentation policies.
Some organisations expect program documentation that an "inexperienced" programmer could read an immediately understand. I think this is a mistake for two reasons:

the cost of creating this level of documentation is high, both in time and frustration. Writing documentation is not fun, writing tedious documentation that no-one will ever read is even less fun. Forcing good programmers to do valueless work will make them ex-employees.
the benefits are less than you might imagine. Any competent programmer will pick up a new environment (even a new programming language) fairly quickly, making the training wheels redundant. If your programmers still need documentation training wheels after a six months, perhaps you've hired the wrong person.
verbose 'learner' documentation hides the important information from the people who need it, reducing the potential benefits of documentation even further

Documentation generators

Many programming languages have a built-in documentation syntax ([1],[2],[3]). Unless you have a really, really good reason not to, you should use these natural processes. Any new programmer already familiar with the language will have a head start on understanding your environment and become productive more quickly.

Because most application programs have many source code files, the application documentation will be spread across these many files, making it hard to find the things you want. This sounds bad, but the answer is to use a generator to extract the source code documentation and assemble it into a useful single library. Don't use this problem as a justification for making programmers write all the documentation in word processing files.

To be useful, generated documentation should be:

Available - in an interoperable format (like HTML) depending on your specific environment.
Navigable and searchable - if I can't find what I'm looking for, what's the point...
Up to date - use the 'natural' update processes in your environment (such as commits to a source code control system) and automatically run the extract/generate process regularly. Include a date stamp (or version stamp) on the output so that readers know how up to date the documentation is (or isn't...)