Slashdot Mirror
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.'"
I took a class at University many moons ago in software documentation. I got an 'A', and it was a valuable class in that I learned I sucked at it. (But I was better than most of the students)
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.
All ideas^H^H^H^H^Hprocesses in this post are Patent Pending. (as well as the process of patenting all postings)
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.
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.
"The weirdest thing about a mind, is that every answer that you find, is the basis of a brand new cliche" -
If by "self-documenting code" you mean code with milti-paragraph long comments in it explaining in detail what each section does and how it's intended to work, with a detailed change log at the top of each section of the code, then I agree with you.
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.
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.
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.
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.
Assorted stuff I do sometimes: Lemuria.org