libRUIN

...version 0.2.0 is out! Holy cow, it's been four and a half years. There are a ton of improvements (do see the NEWS file if you're interested), but just as significantly, this release was made possible by improvements in and releases of a bunch of libRUIN's dependencies -- specifically GNU Guile and the SCSS and SDOM Scheme libraries.

And there were improvements (I hope) to my thinking about software development. If I can wax enlightened for a moment, here are a few observations / edicts that occurred to me as I was working on this release:

Avoid friction in code by getting the data model right.

I've found while working on libRUIN and other projects that code that's difficult to extend or refactor is often the result of an incomplete or incorrect data model. When I sketched out the initial architecture for the library, I think I was trying to keep the number of data structures it depended on low, both in the user-facing API and the internals. If data structure A has the same general shape as data structure B, I thought, why not just wedge A into this B-shaped hole? In retrospect, the additional size and complexity created by adding a few new struct typedefs was trivial compared to the disadvantages in legibility and flexibility brough about by inappropriate re-use of data structures. So: If your model needs a rich set of data structures to be accurate, so be it!

When a specification suggests a model, try that one first.

I spent a long time trying to figure out which parts of the CSS recommendation I could ignore by virtue of my only needing to render markup to a terminal. In doing so, though, I failed to pick up on the fact that a lot of the conceptual framework suggested by the recommendation is actually prescribed by it as well. For example, the "box model" isn't just a useful way of thinking about layout and rendering; it's really quite difficult to implement certain features of the recommendation without actually creating a first class representation of boxes. In retrospect this seems obvious, but at the time I was sure there was no way all of the formal complexity I saw in the spec could possibly be required for the work I was doing. The deeper I got, though, the clearer it became that the recommendation was the result of a long and fruitful two-way collaboration between the standards body and a number of successful "reference" implementations, and that ignoring the models derived from this relationship was actually making my life more difficult: Implementing support for things like the "white-space" property would be practically impossible unless I'd also baked the concepts of line boxes and inline content splits into my code. And I suspect a lot of successful specifications have in common the property that they are both describing requirements as well as the shortest path to meeting them. So: Until you've got a reason to do otherwise, let the specification guide your thinking.

Unit tests are worth it.

The original "test suite" for libRUIN was a set of XHTML documents and accompanying stylesheets from the W3C's CSS2.1 site. When I wanted to verify that a new feature was working or that I hadn't broken anything, I would feed these documents into a sample application and visually inspect the output to make sure it looked right. Obviously, moving to a suite of automated tests for each phase of the rendering pipeline made assessing the quality of the code much quicker. But I think the real benefit of unit tests is more subtle. By applying compile- and execution-time constraints to code, you control the way in which it can change. And by requiring that your code have entry points for unit tests to call, they enforce a layered, more modular architecture. Unit tests apply pressure on code that keeps it in good shape.

(This is probably all covered by a bunch of books and web sites about testing that I haven't read.)

That's all I've got. Take a look at libRUIN, and jump in if you can -- there's a ton more shit to do.