How To Get Developers To Document Code

snydeq writes "Poorly documented code? Chances are the problem lies not in your programmers, but in your process, writes Fatal Exception's Neil McAllister. '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,' McAllister writes, adding that to establish a culture of documentation 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.'"

Comments

Don't Accept

[Aladrin]

Or simply don't accept code that isn't up to snuff. That includes documentation and testing. Peer review will help make this happen automatically. Here's how it goes:

"I can't tell what this code is supposed to do."
"It toggles the widget's status."
"Is that documented somewhere?"
"No."
"Let's get that done."

You don't have to have this happen too many times before you just do it to avoid that. Same as all the other good code practices.

If you aren't doing peer review, you aren't getting the best code you could. It seems painful at first, but good developers actually like getting feedback on their code, and improving it. It isn't long before any good developer comes to desire it, instead of dread it.

Re:How to poke a dead body

[Asic Eng]

It's a pity you didn't read the article, because you are one of the people who could benefit from it.

What happens if your only management tool is badgering? People are going to be frustrated and bored. Their productivity will go down, the quality of their output will be reduced. You'll respond with more badgering and the situation will get worse. You can of course fire them, or they might look for more fun places to work by themselves, but then you are in the worst case scenario with heaps of undocumented code and no access to the people who understand it.

This is basically unavoidable, because working creatively means - among other things - that you'll have to motivate yourself to do the work. It's not as easy as picking up a shovel and doing the only thing you can do with it (the work there is in the shoveling, though). Unfortunately the energy people have to motivate themselves is not unlimited. The harder a place of work makes it, the less the employees will succeed. Any basic management handbook will tell you that, any research available on the topic will tell you that - but still people prefer to manage by what they think ought to be true, instead of what's known to be true.