Martin Fowler: Code as Documentation

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.

3 thoughts on “Martin Fowler: Code as Documentation

  1. Stephen (Sly) Gryphon

    “spending some time analysing the amount of time spent around the various design, coding, management, release and documentation components in software projects”

    Steve McConnell’s book “Code Complete” (I have the recent 2nd Ed) has some stats on activities, collated from numerous [listed] sources in Ch 27.

    In short, proportion of time can vary based on project size, with small projects (< 2k LoC) taking up 65% of time in construction (the book focuses on contruction), with 10% architecture, and 12.5% each integration and system testing.

    Requirements work is not included in the above, as it does not have as direct a relationship with size.

    The construction component is split into detailed design (15%), coding and debugging (27.5%), and developer testing (22.5%).

    Medium projects (32k LoC) are only about 50% construction, with actual coding being squeezed the most, and for large projects (512k LoC) only about 30% of time is in construction broken up into 15% [still] detailed design, 7.5% coding and debugging, and 7.5% developer testing.

    Of course, good code (function names, etc) always make the best documentation. It can also vary if things are only for internal use, or if you are producing an API for others.

    There are still issues which are _not_ captured explicity in functional code, such as the higher level abstraction/purpose, why a particular design was chosen, and what alternatives were rejected.

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s