How to get developers to document their code

Poorly documented code? Chances are the problem lies not in your programmers, but in your process

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.

1 2 Page 1
From CIO: 8 Free Online Courses to Grow Your Tech Skills
Notice to our Readers
We're now using social media to take your comments and feedback. Learn more about this here.