I have spent this last working week, before going on vacation and parental leave for the rest of the year, helping a colleague of mine (and friend) to gain enough of an understanding to take over my project. It has been quite easy, since we’ve known each other for a long time, and worked together several years. So, we had lots of common knowledge and points of reference already, that would otherwise have had to be established throughout the transferring of knowledge.

My goal donor asked me, “You have documented this, haven’t you?” to which I replied, “No, except for the 570 or so automated test cases Malte and I have written during the course of the project.” Each test case captures a micro-scenario in the life of the system, by setting up the objects involved, telling them to do something together, and verifying the outcome. And the fact that they are executable means that a programmer new to a team, besides having an explanation of the code to read, written in code itself, can execute that codee to see if the system still works. So it’s better than documentation.

In the case of this project, the most difficult thing to explain is the problem domain. Few people, I guess/hope, would disagree with the statement that the knowledge of any problem domain is best transferred in a discussion between the people who know it, and the people who needs to know. It’s fairly apparent that the nuances are different to convey in text. You’d have to have a combination of prose and diagrams showing the flow of the organization, or whatever. Why should it be any different for the software that models that organization and offers supporting services to it?

What’s more difficult is to convey the bigger picture in test code. It’s surely not impossible, but again, nothing beats face-to-face discussion. So what I did was to draw some improvised object diagrams showing key scenarios of the system, and handed them to Robert (the colleague/friend) the week before. Then the first day, I talked about both the problem domain and the architecture of the system, at the same time. The diagrams make up one view of the system, the problem domain makes up another, and the architecture, explained in the context of the problem domain, makes up yet another.

Perhaps what’s important is many different views of, or approaches to the system. Yet another approach was to get our hands on some real code, implementing an item off the to-do list. In the light of this, documents seem like the worst alternative, for situations where the original team is no longer there to explain. But there’s still the view of the problem domain, which should provide lots of clues to the programmer as he/she reads code.

The assumption that lies behind the question “You have documented this, haven’t you?” is that code is inherently unreadable and that there must be a manual to explain it. Many projects indeed are like that. Many projects have grand vapor architectures that exists only in the minds of those who have devised them, and can’t be found anywhere in the code. Any document in such a case only reflects the vapor architecture, and is of little help to understanding the code. Let’s hope there are still survivors to answer your questions.