jvdb.org Blog

Little under a month ago, a kick-off event was being held as the official start of the Netherlands Institute for Research on ICT (NIRICT), which included a talk by David Parnas (best known for laying the foundation of object orientation) called Software Documentation: The Research Topic that Computer Science has Neglected. He argues that in order to make any real progress in the area of software quality, software documentation must improve radically. One of the issues he mentions is that reviewing, testing and inspection can only be reliably performed if you have accurate and thorough documentation. (Read the presentation for some of the other issues, it’s quite interesting.)

At the same time, most agile methodologies have been saying that documentation is a thing of the past. In Extreme Programming Explained, Kent Beck states that XP relies on “oral communication, tests, and source code to communicate system structure and intent”, instead of on design documentation. This approach has some problems however, as Lionel Brand pointed out in his 2003 keynote at the European Conference on Software Maintenance and Reengineering: how do you know that the tests you have are complete? How do you know whether everyone working on the project has intellectual control over the technical design? With documentation and reviewing you can find these things out much more easily.

In software maintenance, having good documentation is invaluable when attempting to understand a system you need to maintain that was developed by someone else. The most important part for maintenance is ofcourse the architecture, so having good architecture documentation is essential. To evaluate provided documentation, consider that good software architecture documentation is the following things:

• Up-to-date — obvious perhaps, but something that must always be considered. As a survey by Andrew Forward and Timothy Lethbridge shows, documentation is rarely updated. Technical documents that are not up-to-date are basically exceptionally boring works of fiction, in other words, useless.

• Written by the right people — sometimes organizations let interns or people from outside the project write documentation because the developers didn’t want to. This doesn’t work because as far as architecture is concerned, only the developers that came up with it can properly recognize and understand what is part of it and what is not (as I wrote about before in You can’t measure architecture.) In a 2003 IEEE Software article called Who Needs an Architect?, Martin Fowler cites Ralph Johnson as writing “In most successful software projects, the expert developers working on that project have a shared understanding of the system design. This shared understanding is called ‘architecture.’” So in order to have any chance of getting the message across, those expert developers should have written the documentation.

• Complete — for this you can usually only hope that this follows from the documentation being both up-to-date and written by the right people, since it’s not easily determined if you’re new to a system that needs to be maintained. Personally, I expect several things to be present in an architecture document to be at all usable to facilitate initial understanding of a system. First is a high-level view of the entire system showing all components (usually a diagram of some kind). In addition to this, the following questions must be answered for every component: What are its responsibilities? Why does it exist (in other words, why isn’t it part of another component)? What is its interface? What does this component depend on? These are very broad questions but they must all be answered in detail in order for the document to be worth anything in trying to understand the system it documents.

You could argue that the source code can satisfy these requirements and the first two properties are in fact always satisfied by the source code, but unfortunately, no matter how good your naming convention or directory layout is, the third property is never satisfied by the source code for non-trivial, real-world systems. So architecture documentation is a necessity, at least if you expect maintenance to be required at some point. About the odds of that happening, it’s easy to reference Meir Lehman’s First Law of Software Evolution: “[A real-world] program that is used must be continually adapted else it becomes progressively less satisfactory.”