What I recently realised I learned a while back

The company I'm working for is in a state of transition—actually, it's in multiple states of transition (or a transition point in more than one dimension), but there's only one I'm interested in writing about here and now. The company started as a small startup by a couple of guys at a pace of Oh, crap, we've got to push this new functionality out by Tuesday. This, needless to say, is not the ideal environment for well-planned over-arching project designs, in-depth testing, or detailed documentation, and accordingly, these things are lacking from the older parts of the system. I make this very explicit because I do not want to come off as disparaging the intelligence or skill of the people who wrote these things. (This is not mere self-preservation: They worked under a particular set of constraints, and did what they could with it. I look at things very differently and with a critical eye, but I also recognise that my constraints are radically different.) Some old code bits are crap, but they are crap for respectable reasons.

That being said, the codebase of the company is in long-term and ongoing transition. The old bits of the system are patched together on the basis of Get it working right now; nothing else matters 'cause we'll go out of business if we can't meet our deadlines. The newer parts of the system do increasingly have all the good things I want to see in a software product: Modular, object-oriented design, unit tests, and documentation. It's very far from perfect, but transition, like I said: That's the direction in which it is moving, and this is as it should be. It would of course be nice if it could have been thus from the beginning, but this is the real world and we work with the constraints we have.

Somewhat to my surprise, I find myself being proactive and pushing for improvements in some areas that I've never really paid much attention to before. Unit testing is one—I've known rationally how important they are, but I've never really written them before I started doing it at work (with PHPUnit). Documentation is another—part of me feels the hacker's stereotypical frustration at having to write it (Just read the damned code!), but here I am, writing beautifully formatted docblocks à la Javadoc for extraction and HTML presentation with PhpDocumentor, and urging people to do the same.

Reflecting upon these changes, I realise that three things pushed me to this place, in the form of good and bad experiences, or perhaps more poignantly, good and bad examples. First, during one of my graduate courses, I (along with another guy) did some hacking of one of the open source .NET frameworks—actually we looked at two, both Mono and (if I recall correctly) Portable.NET. One of these—I believe it was Mono, but I won't swear to it—taught me how catastrophic it can be to have poor documentation. Existing developers are easily blind to such things because the oft-used parts of the system become ingrained in working memory; things that are desperately non-obvious to newcomers have become obvious by the time they get to a point where they are in a position to make the changes necessary to make it obvious… In short, at any rate, we had to abandon one of the frameworks because no documentation made it clear how the system was organised, so we couldn't even locate the places where we needed to make modifications.

The second transforming experience was the coding I did while I worked on my master's thesis—modifying the Python interpreter to support distributed computation, remote calls, and so forth. This involved making some rather sweeping changes, such as modifying the PyObject_HEAD macro which is present in every Python object in the entire system. When modifying some of the lowest-level systems bits, and when modifying every single object the interpreter creates, there's an awful lot of room for things to go wrong, and of course, many things did. Some of them did so obviously, and some did so very obscurely. It very rapidly became clear to me that without CPython's comprehensive suite of unit tests, there is no way in Hell (or elsewhere) that I would have caught some of those errors, and ones that I did catch would nevertheless have been orders of magnitude more difficult to track down.

In other words, these experiences showed me that without documentation, is is extremely difficult to know where or how to tackle a problem, and learning curves become much steeper than they really need to be; also that a large application needs unit tests to be robust in the face of changes. It is not, after all, chiefly static correctness we test for with unit tests; rather, we want to establish that, given a correct application, when we change it, we haven't broken it. We developers want to find the bugs; we don't want users to point them out to us (especially not when they've paid for the software).

Of course, I already knew these things, in the sense that I'd read them, considered them, and agreed with the same conclusions I just presented, but they say you never truly learn to fear fire until you've been burned; so I never truly appreciated the value of these things until I experienced them for myself. Don't let this be an excuse, though; if you're working on an application, write unit tests and comprehensive documentation. There is time enough for you to learn the hard way later, when for one reason or another you don't have access to these commodities.

The third experience, of course, is work, where I have the opportunity to see both sides of these issues. A system in transition, part of our code base is properly organised, and parts are a mess. Some bits are unit tested, and some will break in silent and obscure manners. Some parts have excellent documentation, and other parts are so utterly undocumented that I don't even know they exist until I've reimplemented them and somebody asks me why I didn't use the existing code. This not only drives home old lessons deeper, it also gives me an opportunity to aid in transition, and it has taught me refactoring (not least my own code, which I rough out in a sort of draft form and rework in iterations until it has a design I am happy with—I have the luxury of working on a separate module; no one but I cares if I change my APIs).

This is very interesting, and a good learning and formative experience, and I am glad to be where I am, working what I am working on. All the same, I hope that the next project I work on (at some point I do want to give some attention to PhpDocumentor and its memory issues with large codebases…) has documentation and unit tests. I've learned the hard way; I don't need to learn the hard way again.