Reading skills…

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 seen 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.