Fading Memories

No, apidocs writing is not less interesting, I never said that. I like writing api documentation, but I start with it. It's part of the design phase. I like it. Unfortunately as code changes, the documentation doesn't change automatically. And since a simple code change can hit many classes, Adriaan will have many reasons to get angry because writing documentation while coding breaks the flow. And breaking the flow is bad.

And Benjamin -- I work on KMyBigApp and am not interested in working on kdelibs; in fact I promised myself I never would. Not because of any lack of professionalism, of which I have oodles, but because I believe that KMyBigApps are quite essential. It's after all why the library exists.

Anyway api documentation and unittests are not the same thing; and while I haven't figured out how to write unittests for classes in a six year old application that's had four maintainers and where everything depends on everything, I'm at least working on un-tangling the knot so I can start making unittests for new classes.

In bullet points:

• Unittests are the single biggest improvement to a development process you can introduce.
• Apidox are part of the specification of a class and are written before the code is written.
• Our tools should help us keep the documentation up to date, not badgering, nagging or annoying developers who may some ting better to do at any given moment.
• Talking about apidox and unittests in the same breath is silly. They are different things, as anyone knows who has seem hundreds of unit-tests for uncommented classes and reams of javadoc for untested libraries.
• It's not pleasing to a tidy mind, but even tidy minds have to accept that work in progress means that there may be temporary breakage.

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 is 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!