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.'"
Hire document experts (Score:5, Interesting)
The teacher, with a PhD in English, was a master. She probably couldn't code worth much, but she could take unclear concepts and make them clear enough for a newbie.
As long as you hire great programmers you are going to get great programs. If you want great documentation, you need a great documentor.
Documentation not always worth it (Score:5, Interesting)
I'm growing increasingly convinced that in many situations, code only requires a minimal amount of documentation.
Code under development changes rapidly, so most of that documentation would never get used. And lots of code is best explained by the code itself plus small, local comments, rather than by separate, copious documentation. And then there's the fact that software often gets discarded before anyone would need to make the kinds of modifications that required extensive documentation.
It seems like sometimes, people who call for extensive documentation do so from the intuition that it's a diligent, long-term-smart strategy. I think the picture is muddier than that.
Re:How to poke a dead body (Score:5, Interesting)
True but like it or not people don't do it. You can bitch that people should do it, but when they don't what then? You could fire them, but IME some of the people who write the best code by other metrics (reliability, bugs fixed, or just taking on a task no-one wants) are poor at documenting it themselves.
Do you fire people for not documenting code, discipline them? Is it worth fighting the battle if you just need to get the product out/fix the current problems/develop the next thing.
IME code quality always comes back to bite you, if you write bad code/undocumented then soon enough it will come back and bite you yourself when you come back to maintain/modify. If I don't provide documentation to others then I end up with more support requests so it's worth me doing that balancing act, it's not management's judgement call to make.
As for dealing with other people undocumented code, that's just a skill you need to have as an engineer, like being fluent in multiple languages many of which won't be your choice. You think I want this tool chain to be written in TCL? Should I then port it to my favourite language (e.g. perl) what if the next poerson to support it prefers python? It's just part of engineering that everyone else's code will look rubbish and undocumented to you. Even when it is documented you'll then think the documentation is overkill.
Yes it's rubbish, yes TFA makes some suggestions, some might work, some might not, but you can't just say it's your job to document and walk off, in real life we have to actually deal with problems and the reality that it doesn't happen as it should.
Surely I'm not the only one (Score:4, Interesting)
I've never had a problem of incentive or motivation to document my code; my problem is and always has been time.
Documenting anything other than conceptual stuff from the beginning is a bit of a waste (though far from a complete one) because the final product (due to bug fixes/spec changes/etc) never matches what you set out to do.
So when you do get to the point of post-testing where the code has stabilized and it's time to really sit down and document everything fully you're being given new stuff to work on. Sure I can (and do) raise a bit of a fuss about it and explain that if it doesn't get documented *now* it'll never get documented *well*. That always seems to fall on deaf ears though.
I think a lot of it is that the deserved biting in the ass never comes. Shortened product life cycles and customers that have become (wrongly) more tolerant of buggy software in production environments means that you can stumble through with a vague knowledge of the product and never really get fucked. It's the same basic reason that so many bad programmers have jobs.
Re:Hire document experts (Score:5, Interesting)
The teacher, with a PhD in English, was a master. She probably couldn't code worth much, but she could take unclear concepts and make them clear enough for a newbie.
As long as you hire great programmers you are going to get great programs. If you want great documentation, you need a great documentor.
it's funny you should mention this, because somewhere about 3 years ago wasn't there a slashdot article about some entrepreneur who didn't hire computer science majors (this was the U.S...) he hired english language majors and then trained them to program?
the end-result was that he got people who produced better results because they were better able to express themselves and had already been trained to handle and comprehend more complex structures than people who thought they could program.
design document vs. documenting source code? (Score:4, Interesting)
The first camp of developers just wants to get in and start coding. They often say "I need to code to figure it out." The actual web site works well, but new developers have a tough time maintaining that same site. The original developers are pretty much the only ones that can change the critical aspects of the site, and even then, as time goes by, that becomes difficult. But, they got the site up and live in the time allotted. And they wrote a 2 page "design document" when they were done - the doc was useless.
The second camp of developers writes a 50 page design, then starts coding. The actual web site works well, but the overall time to get the site up and live took 5 times longer (that includes the time to document.) The documentation evolved with the changes that were made along the way. Maintaining this same site went well at first, since the documentation was great. But, the docs slowly get neglected, and in a couple years, this site is difficult to maintain.
In the end, perhaps there is a happy medium. A "good enough" design document, and get started coding relatively soon. I used to lean toward the second camp, but now I lean toward the first camp
Re:How to poke a dead body (Score:2, Interesting)
no, you can keep badgering them to do their job properly, with the usual restrictions if they don't.
For example, what happens if coder A decides he doesn't want to use the company standards to write code, or he decides that writing the stock-keeping module is boring and works on an Android app instead? The same goes for not writing the support documentation to the minimum standard too.
I find that the process needs to say that no application is accepted as delivered until the minimum docs are supplied along with it. The docs should be enough that someone else can install it (as someone else usually does). Coders who don;t do the work properly get taken off their current code and put back on their old stuff until it's right. That includes the doc part.
Coders may thing they're some kind of elite, but they have to play according the the rules that are set by the company. If company requires docs, then docs is what they get.
So, yes, you're right that poor quality code bites you back, but that's still no excuse to allow guys who want to deliver the poor quality code and then let some other maintenance engineer maintain and support it (there are enough places where dev and maintenance are split tasks, this is bad IMHO)
Re:code documents itself (Score:5, Interesting)
However IME to most developers "self-documenting code" means something more like "you should be smart enough to know how this works from reading my semi-descriptive variable names". I've seen comments like "Here's the main routine. This is fun" in some code that I've picked up and had to maintain. Made me shake my head at the time.
When I first started my career, I met a developer who put a comment on almost every line of his code. When I asked him why, he said, "because I try to code like the next person who's going to look at what I did is an idiot. And it usually is. It's usually me". I laughed at the time, but as I've grown older I've come to realize how true it is.
make them troubleshoot it (Score:4, Interesting)
I work for a firm that conducts a periodic release of code to its production environment. Those of us who regularly work the "release night" know what it means to document code well (and no, it's not just comments in the code). What our firm, and others like us, needs to do is rotate everyone through that situation, or others like it, so that they can see the flipside of their effort. Having to troubleshoot poorly documented code is a good way to instill in a developer good documentation habits.
Re:How to poke a dead body (Score:4, Interesting)
At my company our process now is built around Design By Contract. Since C++ doesn't have all of the DBC concepts built in as language features, we use comments and macros to define the contract for each class, method or function. The comments include pre conditions, post conditions and the testable restrictions on input parameters and return results (i.e. param x must be between 1 and 10, possible return results are -1,0 or 1). These comments are implemented by macros that do the actual verification.
We then do rigorous code review--if your methods aren't commented and the macros don't match the comments, your code is rejected. Therefore all of the code in our repository is commented and the quality of the comments are exceptionally good. What's more, all of our code is inherently testable. We also don't mark a module "done" until it has 100% test coverage from our automated test suite.
So far in the 18 months we've been doing this process, no one has complained of the "burden" of doing the process and everyone has a much clearer understanding of our system design now. And everyone has had at least once experience where the DBC methodology has found what would otherwise have been difficult bugs to find.
So where we work, comments are part of the code and cannot be omitted. And yes, if we had an engineer who refused to comment he would be fired.
Re:How to poke a dead body (Score:5, Interesting)
Treat documentation as as valuable as code, and it will get done.
Who is it valuable to? When is is valuable to them? It is a complicated time-value of resources problem, and while documentation is very valuable when you need it, your time of need is a) uncertain, and b) in the future, both of which steeply discount its value (but not its cost) in the present.
Decisions are made in the present, and if resources are tight in the present, things of potential value in the future are discounted further.
Re:How to poke a dead body (Score:5, Interesting)
Who is it valuable to?
It's an investment into the future. If you need to pick this project up again one, two or five years down the road, and do any non-trivial changes to it, good (and that means correct, short and to the point, not extensive and theoretical) documentation will save you valuable time.
If it's throwaway code, don't waste time and effort on documentation. If you plan to use it for some time, chances are very high it will need fixes, updates and changes, and documentation will make those a lot easier, faster and cheaper.
Decisions are made in the present, and if resources are tight in the present, things of potential value in the future are discounted further.
Yes. I've been trying for years to tell managers that the only reason that resources are so tight in the present is because they've been thinking that way in the past.
Re:I never understood this... (Score:4, Interesting)
> I have also seen companies with a turnover history due to replacing experienced workers with cheaper labor and this kind of culture will frighten engineers into a protective mode, and they won't comment their code for fear of getting replaced.
I'm living that dream right now; we've replaced a couple hundred experienced, in some cases brilliant IT people with convenience store shelf replenishers with only a few weeks training. So it does happen. And yes, it has been an unmitigated disaster.
The problem is, the people who make the decision are not the people equipped to understand the ramifications of uncommented code. Even when it's pointed out to them that they're going to lose a gigantic amount of crucial tribal knowledge, they'll go ahead, with dollar signs dancing in their eyes, and pull the ripcord anyway. And then what comes out of the bag is a bunch of camping gear instead of a parachute. (Sorry, I just flashed back to an old Road Runner cartoon.)
The point is, not documenting your code is not a good strategy for job retention, for the reason you state (when this behavior is spotted they're more likely to be replaced with someone who's better at documentation) and also for the reason that upper management isn't even aware that code has comments, or that it's not a "procedure", it's the culmination of a lot of knowledge and experience, which isn't easily replaced by a written set of instructions. I would also add that a crew who is secretive, doesn't work well together, and takes forever to fix stuff due to having to reverse-engineer their code, is more likely to be outsourced than people who are doing their jobs properly. I hasten to add, crap happens even to good teams (it did here) but it makes it easier to argue against the decision if you're defending a stellar team.