Jeroen’s weblog

In a recent study on what documentation is used to perform maintenance two conclusions struck me as interesting:

• Engineers claim to be very interested in high-level documentation such as architecture descriptions, but when actually performing maintenance, these same high-level design descriptions are some of the least used documents.
• Besides code, comments and data model which are used the most for obvious reasons, it appears that in practice engineers consult requirements documentation when performing maintenance.

A lot of engineers are confronted with having to modify systems of all sizes that they have no prior experience with. In fact, the more comfortable you are with a system, the least documentation you’ll probably read before doing anything since you already know the code. So in the cases where you just get a login to a source control system and a repository name (or worse: a zipfile or tarball) and you have to find your way around, the first thing would be to find something looking like the entrypoint and reading code and comments along with the database scripts.

When asked to think about what kind of documentation would be useful, I too would say I’d want to have a look at the architecture. But in practice the architecture basically documents what the solution should be and how it should be implemented. However, the solution is already there, coded and ready. In my experience, the question you want answered the most when browsing endless files filled with seemingly unrelated functionality is: What problem is this code supposed to solve anyway? Enter the requirements specification.

Documentation often goes stale after a while, especially once the project is finished and people maintain the software. The documentation itself rarely gets maintained properly. So the solution to this probably doesn’t lie in creating some kind of document to hold this information or adding it to an existing document. In agile circles most practices tell you to name classes, methods, etc. in such a way that it’s easy to figure out what they’re supposed to do. This is a good start but not a complete solution: when you start to figure out what and how an entire system does its work, looking at class and method names is simply way too much work.

The thing that has worked for me on some projects is to put a couple of comments at the top of each source file (or class, if that’s not the same thing in your environment) that explains in a couple of sentences the following things:

• What problem does this code solve? This can be either directly a user requirement but can also be something that the other parts of the system depend on.
• Where does this code fit into the big picture of the system? For instance, the component this code is part of.

Optionally you may add information about dependencies, but namespaces as well as using/import statements are good hints about that already. I’ve been doing this on a couple of projects and have noticed (based on the amount of questions I’ve gotten regarding the code) that it makes it a lot easier for developers to find their way around.