How to get developers to document their code

Finding top-notch developers to join your team is difficult enough. Finding ones who also document their code can seem like a minor miracle.

Let's ignore user-facing documentation for now. Manuals, reference guides, and online help are probably still best left to technical writers -- professionals who specialize in translating technical specs into everyday language. That kind of documentation comes later. During the software development process, however, maintaining a good body of internal-use documentation is essential.

[ Go deep into HTML5 programming with InfoWorld's "HTML5 Megaguide Deep Dive" PDF how-to report. Then understand the issues surrounding HTML5 today in InfoWorld's HTML5 Deep Dive PDF strategy report. | Learn how to secure your Web browsers in InfoWorld's "Web Browser Security Deep Dive" PDF guide. ]

As with any business function, software development teams are always in flux. Programmers might change jobs, move from one department to another, or retire. In the worst-case scenario, illness, injury, or death can sideline team members when you least expect it. Code ages, too; developers can easily forget how their own code works if they haven't touched it for a year or more.

In any of these scenarios, having access to design documents, API specifications, manual pages, and code comments can mean the difference between a shipping product and a blown deadline. Unfortunately, too few developers seem to do a good job of documenting their code. Encouraging them to start can be a difficult challenge -- but not an impossible one.

Why don't programmers document?

There are many reasons developers don't document their code. Some are easier to address than others.

The classic stereotype is the developer who doesn't document out of pure pigheadedness. "Real programmers don't document" is an old chestnut of hacker machismo, one that some coders have sadly taken to heart. You may even encounter programmers who intentionally don't document or even purposely obfuscate their code out of a desire to seem "irreplaceable" or to inflate their own authority in the organization.

These attitudes are toxic and should not be tolerated. But they're also less common than you might think. In the vast majority of cases, developers fail to produce documentation for far more rational reasons.

For starters, when should programmers document their code? It's a fact of life that software modules are often written and rewritten many times before they ship and sometimes again afterward. Developers who begin documenting API implementations too early can often feel like they're committing themselves to design decisions that are only tentative. Moreover, if the specs or requirements later change but no one remembers to rewrite the manual, the result is documentation that's out of date and inaccurate -- a situation that's arguably worse than having no documentation at all. These issues are exacerbated by modern, agile programming methods, which encourage rapid code delivery and iterative development.

Another concern is how much time programmers should devote to documentation. In most organizations, designing, implementing, debugging, and maintaining code are considered a developer's primary activities. But if programmers are evaluated based on these tasks above all others, they are likely to ignore nonessential activities, particularly if your organization relies too heavily on artificial productivity metrics. "Nonessential activities" probably include documentation.

How much documentation is enough?

The good news is that all of these are management concerns, and as such, they can be solved through better management. Realize, however, that any initiative to improve code documentation must come from the top down. Unless management makes documentation a priority, developers won't either. That doesn't just mean issuing directives or criticizing past performance; if software managers want good documentation, they have to enable developers to produce it.

Perhaps the single most important thing software project managers can do to encourage software documentation is to explain what they mean when they ask for it. Developers can often become resentful if they believe they're being asked to walk untrained eyes through their code in baby steps. And they're right!

To comment or not to comment is one of the oldest debates in programming. On one hand, arcane code constructs can be unfathomable to newcomers when they lack any kind of annotation. On the other hand, commenting basic control structures line by line ("loop begins here") serves no purpose and can even make the code harder to read. Outdated comments or ones that obscure the code ("don't touch this variable") are just as harmful as inaccurate API manuals.

Similarly, traditional forms of comprehensive developer documentation have fallen out of favor, particularly among organizations that use agile development methods. Just as line counts are a poor measure of developer productivity, the number of lines or pages of documentation a developer produces is not an accurate measure of the documentation's value.

A useful rule of thumb is that programmers should produce documentation that's "good enough" -- and no more. If it gets the job done, it's probably good enough. Any additions are just as likely to be redundant. If that sounds vague, that's because it is; the important thing is to get developers thinking about what constitutes good documentation.

Techniques for better documentation

Fostering a culture of documentation takes time. Maintaining it requires ongoing reinforcement. Managers should favor the carrot before the stick. Like most people, programmers respond better to incentives than to mandates. Simple praise can go a long way, but managers may find other ways to reward developers. Are your developers occasionally on-call for weekend support duties or late-night update deployments? Consider giving them a break if they volunteer to pick up some extra documentation burden. Of course, financial incentives work, too.

Over the years, a number of development methodologies have been proposed to make code documentation more natural and automatic. On the extreme end of the spectrum is Donald Knuth's concept of "literate programming," in which algorithms are specified using a syntax that approaches those of normal human languages. A more practical technique for most organizations is "self-documenting code," in which programmers adhere to specific naming and structural standards that make code more uniform and comprehensible.

Probably the most effective way to get developers to change their habits, however, is to make documentation a team effort. If a few developers have ownership of a certain module of code, have them give a presentation to the entire team explaining how the code works. In the process of preparing the presentation, they will have done most of the legwork required for formal documentation, and any questions that arise during the presentation will help iron out ambiguities.

Another technique is to have developers tackle documentation in pairs -- in effect, applying the techniques of agile development to the documentation process. If code documentation is not an isolated activity but an active part of a team's common goals, it starts to seem less like a burden and more like an everyday programming function.

If there's one overriding theme of this discussion, it's that code documentation is never a passive process. Too many organizations expect documentation to happen automatically, then lament when it's not there. Unfortunately, writing code documentation is one task for which hindsight is seldom 20/20. The time to start documenting is now. But if it's not happening in your organization, consider that it's probably your process, and not your developers, that must shoulder most of the blame.

This article, "How to get developers to document their code," originally appeared at InfoWorld.com. Read more of Neil McAllister's Fatal Exception blog and follow the latest news in programming at InfoWorld.com. For the latest business technology news, follow InfoWorld.com on Twitter.