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.'"
Once the boss learns about financial advantages of outsourcing.
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)
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.
"If you make people think they're thinking, they'll love you; But if you really make them think, they'll hate you." - DM
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" -
// WHY
int WHAT(...) {
return HOW();
}
-Ouija- poke 53280,11:poke 53281,12
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.
They should be all forced to pass HtDP with all exercises done properly and I bet a lot of them would actually start writing quality code (both quality as in "less bugs" and quality as in "readable"). I love the Amazon comment where a CS PhD admits that reading the book actually taught him to write code properly.
(I have pretty much the same experience, having been subjected years ago to a typical "learn-the-syntax-of-Pascal-and-a-dozen-sorting-algorithms"-style first year of CS at my uni. But they never got around to teaching us how make your brain come up with code like the one in those nice textbook examples in the first place, what are the recurring code patterns (*not* design patterns, mind you). They have never ever once explained how to systematically go (for any problem in general) from a problem formulated in words to a working, readable code. Much like what Dijkstra about the contemporary math education - people memorizing proofs but having no idea how to "do math" in the first place, and teachers hand-waving every objection with saying that studens must "grow some intuition", but never explaining the processes involved explicitly. I believe I eventually got to the point where I started seeing the patterns, but explicitly formulated knowledge could have shortened the process by *years*. Go read the book, do the chores, see for yourself.)
Ezekiel 23:20
In my experience, self-documenting code generally isn't.
Proper documentation never explains what you're doing - that's what the code is for. Documentation explains why you did the things you did, which is difficult to express in self-documenting code.
/**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/
R.I.P - best question ever.
Indeed. The rise of "metrics for job performance" has caused a lot of pain for many sectors of IT.
Judging your programmers by "lines of code written"? Great. They'll write a solution with as many redundant lines of code as possible. They won't comment, because commenting doesn't count. Bugfixes will generally involve patch code that means more lines, rather than cleaning up the code itself.
Judging your IT support by "number of tickets cleared"? Great, you get just what people expect out of those @##$@#$ crapass "phone lines" that bank out of India or Malaysia; they'll do anything to get you off the phone as fast as possible and mark your issue "resolved", whether it is or not. Your in-house guys will have to triage: do we handle 5 "my flash isn't working and I can't watch youtube on company time" issues, or do we handle the issue for one person that's going to take ALL MORNING to resolve but since it's only one ticket, will red-flag us as "not getting enough done" according to The Almighty Metrics.
The Retardicans have started to try to put this into play in the education field, too - teachers' pay will now be dependent on the grades the kids get and their performance on certain tests. You can - as my mother has - put in 70 hour workweeks, staying after every day to tutor kids who have problems, seeking out specialists to help the couple of kids who actually may wind up diagnosed with a learning disability (example: one in particular can write at an 8th-grade level but can't seem to wrap his head around long division after 6 months of trying), trying to figure out what's with the others only to find out come P/T conference night that they aren't learning because they've internalized their parents' opinion of school as glorified daycare and therefore just don't want to pay attention - but the parents DEMAND that they be passed on to the next grade because it'll hurt Little Dumbass McAsswipe Junior's "self esteem" to be held back a grade. You can do all that and it WON'T MATTER, because the kids with learning disabilities won't be diagnosed for another 4 years, and there are enough Dumbass McAsswipe Juniors in the class to pull "the metric" down.
Most of the time the problem doesn't lie with the developer. The developer who actively refuses to document is rare. In my experience, the real problem lies in managers not taking documentation seriously. It is caused by developers being under the stress of deadlines with a manager that really needs this piece of software to be finished yesterday. Managers just don't schedule in any time for documentation.
Another issue the article touches (and I really shouldn't have to say this because of course you have already thoroughly read the entire article. Twice) is that there's the question of when to start documenting, because software and APIs are often subject to change all the time, not in the least because managers keep asking for new or different features.
Personally, I often enjoy writing technical documentation. If I've written good portions of an API or framework that I'm particularly fond of, because it's all done oh-so-clever, you know, I enjoy committing the inner workings to paper to explain to my colleagues how it works and how it's supposed to be used. Unfortunately, like I said before, there often isn't any time to write good documentation and that's a real shame.
If meaningful class, method and variable names and sensible expression constructs are used there is no benefit to be had from comments.
This is a naive viewpoint that gets repeated over and over, most likely from people who've never actually implemented or maintained anything more complicated than "hello, world". As a developer I strive to write the simplest possible code (but no simpler!) to solve a problem, but often that code is complex enough or is based on some non-obvious assumptions (device drivers, anyone?) that I can't even remember later exactly why something was done the way it was. Sure, if you write code for relatively simple problems that don't have to interact with other complicated pieces (like the OS or any libraries), you might get away with little or no documentation within the code, but that's not the world I live in.
I do agree with others that external documentation is just as if not more important than internal comments. And while I'm very good with internal comments, I have to sheepishly admit I pretty much suck at doing the arguably more useful external documentation. Perhaps I haven't been adequately incentivised to do that, but then in most environments I've worked in, I get poked fun at for the level of comments I put in my code, not because they are excessive or unnecessary, but because most other code has almost no comments at all, so my code tends to stick out more than it should.
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.
Maybe it's a sign that the developer really is busy. Most places I've worked it's the developers who ask for additional project time to document code and aren't granted it because it's seen as a non profit generating part of the project (why have coders writing documentation for a finished project when they could be building the new project). It's shooting yourself in the foot for the future if you ever need to change anything in the code, but again, if that time is billable then efficiency savings from proper documentation are a very hard sell.
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.
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.
I totally agree.
You want to know how to make developers document? Give them time to do it. Do not give them another project until the one they've just deployed is documented. Factor in time for documentation when quoting for the time taken to complete a project, and don't treat documentation time as "pad" time that can be consumed by the project when it overruns its overly-optimistic deadline.
Treat documentation as as valuable as code, and it will get done.
Just because you're paranoid doesn't mean there isn't an invisible demon about to eat your face
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.
It is their job. If they don't do it, fire them. If you can't fire them for some reason, give them crap reviews and crap tasks.
I envy you that you work somewhere where there is an excess of perfect people that you can do this. In my experience there are some really clever people out there who have some personality flaws, and there are lots of people who stick to the rules and are quite average. Personally I'd rather try and work with flawed brilliant people and accept undocumented but efficient, quick, timely code than get a monkey who follows the rules and produces acceptable code. You may not choose that trade off and that's fine we will probably never agree there... ;-)
Now if you're telling me you can get someone who does everything brilliantly then great, but lots of great engineers are divas so whilst you can try and lead them, to give someone a poor review (when they saved your behind at the last customer demo) because that code they cooked up lacks documentation then I'm once again wondering how on earth I ended up with such an awesome job.
FWIW I used to have a manager whose approach to people who he thought produced unmanageable/undocumented code was to stick them into a code maintenance/system integration role. It was interesting how quickly you then started complaining about other people's code and documenting both theirs and yours
Oh, and no function should be longer than about 20 lines.
Where's my funny mod points when I need them?
All non-trivial code is crap and could be improved in some way
I would say all code is crap and could be improved, the problem is where and for what purpose? Code with too much abstraction is crap, so is code with 1 line per function, so is code with too many things happening on one line, so is code that is too tied to the particular hardware, so is code that ignores what the toolkit libraries can do, so is code that is written in the wrong language for the problem you are solving, so is code that is a complete re-write, so is code that wasn't profiled properly. etc
Any blanket rule you can make has exceptions and while I am all for coding standards and code reviews rules are there to make you think before you break them, nothing more.
"The weirdest thing about a mind, is that every answer that you find, is the basis of a brand new cliche" -
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.
Metrics aren't bad in themselves, but bad metrics are terrible. Lines of code written is a really bad metric.
I've seen the ticket one happen too many times. Someone will call because n people are having a problem, and ask if the hell desk person wants the info on the other people so they can get fixed, too. Nope. Have them call and open tickets. More tickets with simple, known solutions == more tickets closed quickly.
And yeah, the same is true of teachers. Teachers *should* be judged on their effectiveness, but the way we do it is often nonsense. Don't ask me to come up with the method, the one thing I DO know is that someone with no experience in the field (me) should not be the one divining metrics to measure them. That said, we've all been through school, and some of us have put kids through school. You know some teachers are better than others, and some are really bad. We do want to find ways to encourage all of them to be better and to get the worst to go do something else. There are also fit issues between teachers and children. The teacher you found to be great for your kid might be average or bad for mine.
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.
Unruly behavior like refusing to follow coding standards can be a sign of a problem employee that you have to let go, but it can also be a sign that all of your developers perceive your policies to be detrimental to both them and the business, and this person is the only employee you've got that cares more about the company and his craft than about his immediate bosses' sensibilities. That sort of courage could easily derive from the fact that perhaps this person is the only person who is in demand enough that he could easily find a job elsewhere. Managing by badgering, lashing and threats of firerings is a great way to lose the respect of everyone working for you. That's when suddenly productivity drops and bugs go up for no apparent reason.
If you are a leader, and if people thought that a policy was god-awful, and then suddenly they all stop talking about it ever to you, that probably means that they have given up on your organization due to your leadership, and now they are just going in from 9-5, doing whatever you say to keep you happy, while not showing any initiative to bend your policies in the interest of the business - they are probably also looking for a different job at the same time.
An employee who does just exactly what you say is the worst possible kind of disaster waiting to happen. You absolutely need your employees to question you. "oh, you need me to quickly finish this piece of code because minor customer X wants it now? Well, I happen to know that that same routine will have lots of bugs if not done carefully, and we are going to use it also to give to our major customer Y, to whose interests it is vital that this code work perfectly, but I won't question you by mentioning that and instead give you what you asked for." It's called malicious compliance. If you insist that employees ignore the good of the business and follow your orders to the letters instead, then watch out, you may eventually break some of them to give you what you ask for, and you won't like it.
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