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.'"
It's called doing your job.
When the foot seeks the place of the head, the line is crossed. Know your place. Keep your place. Be a shoe.
In this case, mandate works best because this is something that the developer SHOULD be doing anyways. Not documenting your code is inexcusable.
I prefer the theory that well developed code is it's own documentation. (believe this comes from reading a lot from Uncle Bob)
Crud loads of javadoc/msdn like documents aren't as effective as readable code and a few real world examples.
Management says "do X" as fast as you can. Programmer does X and report back. Documentation, like proper testing or elegant design, takes time and thus cost money. It often saves cost over the long term but if the management doesn't care why should the programmer ?
If what you need documenting is at the level of comments within a file your problem is not that your programmers aren't writing comments it's that they are not sriting good software. If meaningful class, method and variable names and sensible expression constructs are used there is no benefit to be had from comments.
I'll make an exception for comments to explain why a given piece of code is not actually batshit insane but required to work with a third-party library you have to use.
Producing documentation that spans classes and discusses how things are designed to work at run-time is, however, part of the job.
I guess today is a passable day to die.
You also need a culture that encourages documentation as well. I've met plenty of developers who are thoroughly convinced that the code is the only documentation that anyone would ever need. Here's the problem with that thinking:
void frob_the_splutnik(int a, int b) {
s = get_splutnik()
s.frob(a, b)
}
That's definitely concise, and perfectly clear, but only if you already know what a splutnik is or why you'd want to frob it, and what a and b are supposed to signify. If you're a developer unfamiliar with this code base though, you have no clue what this means, not because you're dumb but because you've never encountered any of the concepts that the original coder had in mind.
I am officially gone from
// WHY
int WHAT(...) {
return HOW();
}
-Ouija- poke 53280,11:poke 53281,12
As someone who's started a new position and using classes with No comments, I can say I've wasted a good deal of time trying to figure out what certain public methods and certain classes do. They've used good naming conventions, but even so there is some subtly about what is done that could have used some explaining, plus looking through 1000s of lines of code before using a method isn't time effective. Its would be far easier for me to read through method header with inputs/outputs than to slog through code trying to figure out if this is the method I want. I don't want every line commented (I've seen that some placws), just the jist .
I came from an internal api writing group, and those using our code would just ask us questions if they couldn't figure stuff out, and we rsther they didn't so we documented ..
Examples or some test code I agree are super useful.
I hope to $deity you're not a manager. Your morale must be terrible if you do.
I have to echo other commenters: If you want well documented code, you need to allow sufficient time for said documentation to be written. Failure to do so isn't a failure in programming, it's a failure by management to build realistic timelines based on feedback from programmers.
If your programmers are constantly telling you they need more time, on project after project after project, and it's ALL of them, not just a few complainers, then you need to look in the mirror to find the source of the problem. Go to sales/marketing, read them the riot act about promising impossible deadlines, and get THEM fired if they continue to promise unicorns on a wombat budget.
Never underestimate the power of stupid people in large groups.
Your entire premise rests on a few bad assumptions, however:
#1 - that the PHB will know what the fuck he is doing and adequately schedule enough time to document the code.
#2 - that the marketing fucktards will know what the fuck THEY are doing and not overpromise or promise delivery schedules so tight that the PHB has time to allocate to documentation in the first place.
#3 - that the company bosses are not "doing more with less" and overworking their employees to start with, relying on a down economy to fuck the working class by making everyone too scared to quit (for fear of not finding another job and being unable to support their families or being tied down by the risk of losing medical coverage) do 3-4 persons' jobs.
Now let me tell you how the "real world", the world created by the Retardicans for the last 15 years works:
- Employees ARE, as a general rule, overworked. The upper class HAVE, as a general rule, been playing the "do more with less" card so often that employees are doing the work that 5 years ago was done by 3 people.
- Employees ARE, as a general rule, fucked by the system. Need to find another job? Better hope it covers healthcare. The upper class don't have to give a crap about health care, the poor will never get out of people poor because if they ever did medical bills will put them right back, and the middle class lives in daily fear of losing health care coverage and being put into the poorhouse by medical bills - for themselves, spouses, parents, kids, anyone in the family.
- Managers are fucking assholes whose job it is not to work with the employees, not to ensure that enough time is allocated for things that need doing, but to be slave drivers. We just had a slashdot article covering the latest problem of people feeling too scared to take vacation because of how managers behave about it.
What we need are far stronger worker protections. The Retardicans have been screaming about "obamacare obamacare obamacare" like it's some kind of bogeyman, but actually, single-payer and guaranteed healthcare coverage are GREAT for the working class, because it's removing the iron ball of "healthcare tied to your asshole fucking boss" from their legs and will let more people actually look for better jobs, or even start their own businesses without the fear of one accident or one unexpected illness ruining their entire lives.
Six months from now, long after I've moved on to something completely different, am I going to remember a function's return values? The inner workings of a particularly complex algorithm? Or the reasoning while a special case has to be handled differently?
If it's not going to be obvious to myself later on, it's worth adding a concise comment to explain.
Ita erat quando hic adveni.
I always document my code. It saves time later. Six months down the road I'm not asking myself "why the hell did I do that?" It's for my own protection. I've had programmers tell me that they don't document their code because it's obvious what the code does, and sometimes that's true. But I think at least some of the resistance later to add features or fix bugs has to do with not wanting to struggle to remember what the code does. And -- this is just me, but -- you probably don't want to have a reputation for being uncooperative and not a team player in a down economy.
In a very early job, a guy with more credentials than I wrote a program we all used in a language I didn't know. There was a longstanding bug which he refused to fix [1], and he kept the source in a protected directory. So one night we broke into his account, I scooped the completely undocumented code, figured out the problem (had to change *one* (1) character!) and distributed the new binary. It took him awhile to figure out what happened. Boy was he pissed.
[1] Whether this was a dominance game or he really did not want to try to figure out the code he had written months earlier was a point lost in history.
Oliver's law of assumed responsibility: If you're seen fixing it, you will be blamed for breaking it.
Or they will show you why code comments are a bad idea.
Code comments are usually unmaintainable artifacts; misleading at best.
The best kind of documentation is architectural description of the solution. Everything else is just rubbish. I want to see code comments WHEN they are needed - and the fewer the better. If you write your code in such a manner that it needs documentation, then you might have done a bad job ad writing code.
Example of moments when you NEED to document code: module boundaries, interfaces and implementation hints for when the code needs extension. But by no means should one document EVERY call; but the most important ones. Code samples would help.
Just some programmer's opinion