SAW – post-mortem

Yesterday, I released the 1.0.0 version of SAW.

The master branch now has a 1.0.0 tag on it, and the documentation is up to date. And there was much rejoicing! It’s not much, mainly because no one is using it besides me, which means I have no issues to deal with, no weird bugs that I can’t seem to reproduce… But it doesn’t mean that releasing it publicly is devoid of meaning.

Release early, release often

For the most part, releasing it brings me closure. It is out, it is tagged 1.0.0, it is in the wild, its checklist is empty: it is one less thing I have to worry about. I tend to think about a new project every morning, and this one is the very first that I’ve worked on alone that I feel I can release… Also, I’m a bit of a perfectionist when it comes to writing code, so releasing it means that I’m finally starting to grasp the idea that nothing can ever be perfect. Also, it is a way to do away with my “shyness” and accept the fact that reviews and criticism is the way to grow and improve.

But the thing is… I know I’m missing the point. The goal of releasing early and often is to improve with feedback, while I’m slowly starting to release some “perfect” code with which I do not wish to bother anymore… But I’ve started the year with the resolution to clear my mind and my desk by releasing all the things: finish everything, write documentation, add tests, check the coverage, write huge introspective release posts that are but an excuse to reuse old memes… and that is, anyway, somehow, I think, a step in the right direction.

What’s a “documentation”?

Which brings me (somehow) to the main subject I wanted to address in this small post-mortem: writing documentation. It is a difficult subject, and much has already been said about it. But writing SAW’s documentation made me realize a few things that I had yet to understand by myself.

So, what’s a “documentation”? You know, that’s the… thing that goes along with the code and that… explains the code I guess? “Documentation” is a broad term, that can describe many things. The first thing I realized was: for whom am I writing this? And why do I need to write things for them?

So, SAW is a library. Its goal is to be used by other developers who want to benefit from the features it offers. My target is therefore: “other developers”. But that is yet again a broad term: to be more precise, I’d like to target developers that would want to know how to use it, not hypothetical developers willing to contribute to it. So, what I really want to do is explain the public API.

The code’s not enough

For a long time, I strongly believed that code ought to be its own documentation. That if your code it not readable and that one cannot easily understand what it does by reading it, then there’s something wrong with it, go fix it! Documentation, in my mind, had only one purpose: explain the big picture. Let the code speak for the details. I therefore used to be strongly opposed to comments in the code, cluttering a perfectly readable file with verbose documentation.

//! Creates / open the database in given file
/*!
\param filename: the database file name
*/
void connect(std::string filename);

To this day I still believe in small, easily-readable, not cluttered by comments code files. However, I’ve came to realize that there are things that are worth documenting between the top-level big picture and the deep-down lines of code. Those are, for instance, the guarantees of each method:

• this method will complete in O(n);
• this method is thread-safe;
• this method has such side effect.

The more strict the language, the most this is enforced by the code itself. But SAW is made with C++, which is far too permissive…

Loose correlation

SAW’s documentation is therefore mostly a list of all the publicly accessible class and methods, sometimes crudely explained and annotated, with a tutorial that tries to highlight the big picture of it all. But, on top of being a bit short, it suffers from the main issue of hand-written documentation (as opposed to computer generated documentation): the slightest change in the codebase needs to be reflected in it manually, because nothing is worse than a misleading documentation.

This leads me to end this on an internal contradiction: I don’t want comments polluting my code files, but I would like the documentation to be fully generated from the code… There’s no good answer. I guess that’s the price to pay for still working with text files.

“Source code in files. How quaint.”
Attributed to Kent Beck

Well, anyway, here it is. Not perfect, but released. One down, a few more to go!