Why Johnny Can’t Document

I had some plans for a massive web page on software and software management, but it occurred to me that it’d be better to blog about it instead, in dribs and drabs. So here we go.  (I should mention that though I’ve worked in the industry for 25 years, it’s all been in software shops.  I recently interviewed with a huge megacorporation that can afford to have 150 people paid to do nothing but write architecture documents; that’s another world and I can’t help you there.)

Today’s question is, why can’t programmers write documentation?  Are they just lazy, or what? 

The brief answer is, it doesn’t match how they think.  Programmers are good at dividing a huge problem into little pieces, chunklets simple enough to be understood by a pedantic idiot, that is, a computer.  It already takes a special mind to be able to think in terms of the little pieces and to master the petty, arcane way the idiot insists on being addressed in.  It’s rare that the developer can talk to human beings as well.

If you corral the programmers into a room and force them to address the lack of internal documentation– something they’ll readily admit is a Bad Thing– then they’ll come up with a way to make documentation look like code, or come out of code.  They’ll look at something like this method signature

public void Deposit(decimal amount) 

and produce something like this:

Method name: Deposit
Return value: void
Description: Make a deposit
Argument list:
     amount    decimal    (input)    amount to deposit

In other words, their idea of documentation is to list out what’s obvious to any programmer reading the method signature.  This does nothing except create something else to maintain or more likely to get out of sync with the code, but to the programmer it has the advantage that he can write a program to generate the “documentation” automatically. 

In a small software shop this sort of thing will be done for one or two code files and then quietly forgotten.

What do you do instead? 

If you really want internal design documents– and they are nice for training other programmers, for debugging, for sharing techniques– then you have to make time for them.  Developers don’t include design or documentation in the estimates they give, and since their estimates are low anyway, they’re usually skipped.  So include the documents as deliverables and make time for them in the project plan.  (Often there’s downtime at the beginning of the project anyway while the honchos are arguing over what to do, so that’s a good time for this.  This is also when the code is freshest in people’s minds.)

At my last job we had a wiki for design, ideas, documentation, whatever.  That works– at least, it works better than paper.  In this area the perfect is the enemy of the good: creating good paper documentation is difficult and time-consuming and people tend not to do it.  Slapping the best bits from an e-mail chain into the wiki, by contrast, takes only a few minutes.

The best place for documentation, though, is in the code.  Good programmers should explain what the major methods do, what the class is for, and any tricky procedures or formats, right in the code.  The code is where programmers look anyway, and since the comments are right there, they’re more likely to be maintained.  And it’s in the source control system and requires no extra tools.

(How do you get even that?  The surest way is to do code reviews, which I’ll talk about another time…)


A pleasant oops

I used to read Daniel Davies’ blog every once in a while, by which I mean I’d check it and note that the lazy wanker (he’s British, you see) wasn’t updating. Today I realized that my bookmark pointed to an archive page, so I was able to catch up with several months of random acerbicity.

He’s an economist, but he has the sparkling careless wit that our more earnest nation can never quite manage. In the archives are some fascinating dissections of Freakonomics, quite a lot about Africa, and odd digressions… did you know that a significant source of income for the Ku Klux Klan was selling and dry cleaning those robes?

Fragging your computer for fun and profit

So my four-month-old computer went and ate up its hard drive about a week ago. This sucks, but it was covered by the warranty at least, and it had two unexpected benefits:

  • The stupid OSD that I wrote about months ago has disappeared.
  • Since the reinstall, Fallout 3 hasn’t crashed at all.  Knock on ravaged, post-nuclear wood.

I did lose all my Fallout saves and thus my level 20 character, so I started a new game.  It’s amazing how much easier it is the second time… I had a few hundred caps and quite a few stimpacks before even leaving Springvale.

Xiumei ready for some wasteland action

I’ve repeated some quests, but tried to do some things differently– e.g. going to Galaxy News Radio before Rivet City this time.  The battle with the Super Mutant Behemoth goes a lot easier with backup.

I may also try to explore the map more at lower levels, just so I can get around later without having to put down pairs of giant radscorpions every furlong.

Progressivism that works

I haven’t been in a posting mood lately; sorry about that.  Worse yet, the most interesting book I’ve read lately, James Galbraith’s The Predator State, had to go back to the library.  Man, and I thought I disliked the Republicans.  There’s a lot in it I’d like to talk about, but I’d really like to re-read the book and review the arguments first.

His basic thesis is that the pet economic policies of the right— monetarism, lowering taxes as an incitement to raise savings, small government, deregulation, free trade— were long ago abandoned by Republicans in power and by economists; the only people who still believe in them, defensively, are liberals.

He’s most interesting when he gets down to specifics— e.g. he says that obscene CEO pay was largely the norm in two industries, Wall Street and the tech sector, and that its unintended effect was to create a new aristocratic class: the CEO has no loyalty even to the firm that pays him, but only to his fellow CEOs.

Perhaps the best take-away idea, however, is that deregulation is not (as progressives might suspect) a sop to the business class.  It’s a sop to the worst of the business class.  Regulation is an alliance between progressives and the top companies. Take gas mileage: can reformers decree that cars get 100 mpg?  Certainly not; we have to set goals that can actually be met.  Regulation thus benefits the companies that can meet the goals and still make a profit; and the companies that resist are those that can’t.  These are the ‘predators’ of the title; it’s their interest that the Republicans serve.

Galbraith’s critique goes well beyond this; he chastises liberals for swallowing the worship of the free market, merely hoping to tweak it toward justice.  He thinks that the market fails badly in many ways, and frankly argues for government intervention, social controls on wages, and deficit spending.  His presentation can be a bit breezy, so I’m not sure I follow all his arguments nor agree with them all, but I think he’s quite right that “the market” has become an ideology designed to restrict policy options, which needs to be challenged.