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.