Posted in:

I've been reading a bit on "Agile" development recently, and I like what I am hearing. I didn't pay much attention to it at first, as it all seemed to be about "SCRUM", a project management strategy which is realistically never going to be introduced at the company I am working at (or indeed any of the companies I have worked for).

But one thing that I really like is the willingness to question the usefulness of documentation. Whenever I have been in discussion meetings about software quality, someone always suggests that the answer is for us to write more documentation. If only there were documents describing exactly how things worked, then all would be great. Any piece of code you were about to work on, you could simply look up the relevant document and immediately understand it. After you finish your work, you update the document with your changes. Job done!

There are a number of problems with viewing documentation as the answer to improving software quality.

First of all, at best these documents capture intention - what we planned for the software to do. As we all know, features get cut, added and modified. And the documentation ... well let's just say it never quite gets to the top of the priority pile to update it. Gradually it drifts further and further from reality until it is nothing more than an "elaborate lie".

Second, these documents rarely contain the type of detail a developer wants. Often I find myself writing down the convoluted path of events, function calls and thread signals that lead from an action being initiated to the part of the code that I actually want to change. If only there was a nice diagram I could consult that shows me. But there isn't. Or if there is, it is too simple or simply wrong.

Third, even if there is a great document, that has exactly what you need to know, it is not at all obvious how you know it exists and where to find it. They end up in obscure locations on network drives or internal websites. The person who wrote it acts shocked that you didn't look at it before you asked them, yet quite how you were supposed to become aware of its existence is never considered. The end result is that even when documentation is done well, it is seldom read by those who would benefit most from reading it.

So if documentation is not the answer, what is?

Ultimately, there are two main resources that a developer uses when trying to understand code they are about to modify. First is the person who wrote the code in the first place. Hopefully they are still around, and hopefully they are helpful. They can often save you large amounts of time. Amazingly, many developers will dive right into modifying code they haven't written without thinking of asking the original author whether there is an easy way to accomplish what they want. The end result is often overcomplicated add-ons that introduce subtle bugs, decrease cohesion and tighten coupling.

The second resource is of course the source code itself. The strongest reason for needing to write smaller classes and functions is the need for other developers to understand the code. Code that works but is impenetrably hard to comprehend is bad code. Bug reports should be filed against it. The "if it ain't broke don't fix it" maxim does have a certain wisdom to it, but I would argue that if code is so complex that no one can modify it without breaking it, then it is already broken.

Given a choice between a week of refactoring a complicated class and a week of writing about how it works, I know which I would choose.