Featured White Papers

• What Developers Want: The End of Application Redeploys

Sponsored Links

• Career opportunities at Harman- Careers That’ll Rock Your Socks Off.

  Learn More!

• Developer-friendly Java PDF libraries by Qoppa Software

  Live Demos

• Stop blaming your app! Diagnose Java performance issues.

  Free tool >

• UrbanCode: Go From Continuous Integration to
  Continuous Delivery

  Learn More!

Sponsored Links

Optimize with a SATA RAID Storage Solution
Range of capacities as low as $1250 per TB. Ideal if you currently rely on servers/disks/JBODs

How to get developers to document their code

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

By Neil McAllister, InfoWorld, 01/12/12

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.

For more enterprise computing news, visit InfoWorld. Story copyright InfoWorld Media Group, Inc.