How To Get Developers To Document Code 545
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.'"
Don't Accept (Score:5, Informative)
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 (Score:2, Informative)
It's called doing your job.
And if your job does't measure your comments as part of its "productivity metric"? Like companies that use 'Klocs' to see how much 'work' you've done?
Commnets aren't included when counting. So, it's quite clear that commenting code isn't part of the job.
Re:Mandate works best (Score:4, Informative)
No, it's perfectly excusable.
Not giving your developers time to write documentation, by piling on another deadline as soon as the last bolus of code has been shoved out into production, yet still demanding that documentation somehow appear - that's inexcusable.
Re:How to poke a dead body (Score:1, Informative)
When I code (which is much rarer these days since OOP and functional has ruined programming for me vs. straightforward linear procedural programming), I used to always write the comments and fill in the code below the comments like it was taught before.
Thus: /* Do this */
(code below) /* Do that */
(code below)
and so on.
Yes, many of the lines were self explanatory without the comments, but the point was to be able to read the comments for what the code below does BEFORE EVEN HAVING TO LOOK AT THE CODE. Then, look at the code for changing it or bug-fixing, of course.
IMHO, elegant and even "self-documenting" code isn't as good. I don't care if the approach seems old school, unless I am programming as a job for a company.
Re:How to poke a dead body (Score:5, Informative)
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.
Re:code documents itself (Score:4, Informative)
If by "self-documenting code" you mean code with milti-paragraph long comments
That is not what the term "self-documenting code" means. It actually means the opposite of that. The term refers to code with no comments, where the variable names, function names, etc. are so well-named that comments are less necessary. For example:
float CalcPatients()
{
return bpr * r * o;
}
float EstimateNumberOfPatients()
{
int beds = bedsPerRoom * rooms;
int patients = beds * occupancyRate;
return patients;
}
The latter is the self-documenting version.
Measuring readability (Score:4, Informative)
I think the real problem is trying to measure code readability. Policies and coding standards try to address the issue while avoiding it by mandating frills that they think will kind or "imply" readability - function length, number of spaces in parentheses, badly defined Hungarian notation (dead, thankfully), Javadoc or similar commenting standards, and so on. But there's no getting around the fact that the only way to measure code readability is to read it.
This means that you need to put code review at the centre of the process. Not necessarily anything heavyweight, but just require that one other developer reads and understands the code (and points out any obvious flaws) before committing - with the limit that any questions the reviewer has should only be answered by changes in the code, because a question implies a readability problem. The developer can add comments, or rename variables, or restructure the code to make it clearer, but the end result should be readable code with fewer bugs (bugs live in hard-to-understand code, simply adding some intermediate variables to a complex formula can make them go away).
As long as the code review itself doesn't get bogged down with issues of How The World Should Indent and things like that - that's always a risk with developers looking at each others code.