Apidox

Adriaan de Groot writes about apidox and defect reports — not that I think the two have much to do with each other: unittests and defect rates, yes, and swiss finishing schools and quality of defect reports, there’s a causal connection, definitely. But that’s not important: what’s important is that the api documentation is never going to be complete, perfect or even moderately useful.

And this is why: a reasonable hacker will write his code, and never document the API — and his code will work. A decent hacker will come back and document the API even when not paid for it. An good hacker will write the API documentation first, and then start coding. (A truly excellent hacker will write the API documentation first, then the unit test and only then the code. But he’s on the job full-time.)

But what happens then: the specification phase over, the dox are written, the header file looks fine. Time for the code to be written. And that means stuff changes. Code is plastic — not rigid. But there’s no automated system in KDevelop to update the parameter list in the apidox and there’s no way someone who’s in the flow is even able to break his concentration to update the documentation by hand. It’s not a matter of resources, it’s a matter of doing something that belongs to a different part of the brain, that’s a different activity. Coding is not the same thing as writing prose; any suggestion that people should learn to see these activities as the same thing is ridiculous. Brains don’t work that way.

(And keep in mind: doing A needs B as a prerequisite, which needs C, which needs D, which needs the rest of the alphabet: all the while the code for A is unfinished and quite probably breaks the apidox, which doesn’t matter at all as long as the application isn’t broken.)

And afterwards, when the flow stops and there’s time to reflect, there’s something else that needs attention now — people yelling for a feature, yelling about a bug, yelling because something needs to be done. There isn’t even time in an average day to check whether the apidox are broken: there’s not even time enough to answer all koffice-related mail in a day.

And then, yes, I’m sorry to say, apidox don’t count. There’s stuff that’s more important. And between a working feature that helps someone do his work with my application and a polished API documentation for an unfinished and as yet unused class file — even if the dox will prevent my name from being bandied about… I’ll choose the feature and bear the scorn.

Features cannot be synthesized by users, bugs cannot be solved by users, but developers can read the source and divine the meaning of a class — even if that’s a horrible prospect and should be the last resort.

In short: forcing folks to fix the apidox by badgering them with channel-polluting irc bots won’t work. What will work is fix KDevelop to automatically write and update the apidox during code in an efficient, unobtrusive matter. Whoever cares about apidox — fire up your editor and start coding!