This time last month I read this post by Martin Fowler. In the post Martin puts the case for code as a form of documentation – although he goes to great lengths to stress that is not the only form of documentation, and that it can be good or bad documentation depending on the nature of the code. I didn’t know if I entirely agreed or partially agreed so I decided to put it aside and re-read it at some point in the future (I do this a lot).

At the same time I’ve been spending some time analysing the amount of time spent around the various design, coding, management, release and documentation components in software projects.

While I don’t have any hard data to back it up my gut feeling is that we spent an extremely small amount of time in the design and documentation components and significantly more in the coding and release parts of a project – management is an parallel stream of work which is constantly steering the project towards successful completion (or atleast customer satisfaction).

I feel the reality is that we spend about 1% of our time writing word processed documentation to support software projects – this may be a bit low for some projects, but I doubt its more than 10% for most.

Its a fairly amazing figure (if I am correct) and it actually adds weight to the argument of using code as an important documentation artefact. But how do you create that elusive good code documentation?

A few years ago I worked with an old-C-programmer (are there many young-C-programmers?) and where most of us on the development team were producing some fairly long routines (about a page and a half) he was factoring his code out into about five or ten seperate methods.

At the time I asked him why he did it like that, especially since we as a team had produced a template for implementing these kinds of routines. He said to me that he does it to improve documentation and it wasn’t until I really sat down to analyse his code that I figured out the genius of his implementation.

All of his private methods used very descriptive names. While they were long, they were also very precise and explained perfectly what the piece of containing code did – it made it very easy to read and maintain but when it came to debugging he always found his bugs first – because the methods told the story of what was happening in the stack trace. Anyone who had used our templates were essentially looking into an abyss from whence exceptions were raised.

I think this was a good example of good code documentation when it is both static in the source files but also when it is in action.

This approach works beautifully at the procedural level but as you start layering on the abstractions it can sometimes be hard to distill the design from a series of source files. Personally this is one area where I think patterns help because to an experienced programmer certain class names have obvious linkages and overtime you get a feel for how systems are implemented.

I think that development tools (not UML diagramming tools) can take it one step further and allow us to group classes together into patterns. Tools like Rational’s XDE took steps in that direction but since I wasn’t really a user of it I don’t know what its warts were.

Rather than having a heavy plug-in to design software using patterns I thought it would be useful to have a “Pattern Explorer” which analyses the code-base over time to identify common (and maybe even uncommon) patterns in the code base. The screenshot below is an example of what I am thinking.

Basically – just like with have the Solution Explorer, Team Explorer and Class View, we would also have to Pattern Explorer. I don’t think this would be too hard to implement – especially if it leveraged the existing CodeModel capabilities in Visual Studio.

If this became a common fixture in all IDE’s the ability to grasp the overall design would become much simpler (I think) and it might even give poor quality code documentation a boost by virtue of some brute force analysis and visualisation.