Documenting Code

The most important thing I can stress here is that I truly believe in the value of good documentation and that this article only addresses what I believe is a flaw in some documentation strategies.

Usually a software document begins its life as an accurate description of what a system is doing and how it’s doing it. As the software evolves, the documentation doesn’t always evolve with it and sometimes in fact the divergence between what the software does and what the documentation says it does, becomes a problem. Now I know in theory that documents should be maintained but the reality is that this doesn’t always happen… In a perfect world software would be right first time and every time and requirements would never change, sadly this isn’t a perfect would.

Before we get smug about it, this problem isn’t limited to the software industry I recently tried changing a taillight on my sisters’ car. Since I had never done this on such a new vehicle I decided to use the manual. The manual never mentioned an extra sneaky little nut hidden in the boot that held the enclosure in place. Sadly I used a Brute Force attack which resulted in a trip to the scrap yard for a new taillight …..

In hind sight I can see what happened; boffin engineers designed and documented the perfect taillight enclosure. After a couple roll tests the perfect taillight flew over the ditch, the boffin engineer’s now added the extra sneaky little nut to keep the perfect taillight in place but never updated the now imperfect manual.

So what went wrong, how can something which should be pretty easy to maintain end up costing me, the user, time and money? …. In my honest opinion it’s as a result of the detailed documentation not residing in the right place.

Using my taillight incident for comparison lets explain what I mean by this in terms of software documentation.

The manual can be compared in this case to a Design Specification, the first paragraph that tells me that the car has a taillight which resides at the rear and has a bulb which is red; this can be described as the Functional Specification. In this scenario let’s compare the instructions on changing the bulb to the Technical Specification.

I’ve found that Technical Specifications often contain overly detailed descriptions of code including the actual code … now look at the source code its lucky if it gets a most basic comment. Years down the road and our code has drastically changed, high level business rules haven’t really changed a lot but our implementation has due to evolving code practices. So now those detailed code descriptions within the documentation are useless if not dangerous, assuming like the boffin engineers we haven’t maintained them.

Back to the taillight… What if the instructions to change the bulb were located in the boot next to the taillight enclosure then someone would have realised that the documentation was out of date. When they added the new sneaky little nut they would immediately realise! “Hey this sneaky little nut isn’t in the instructions, this could cause a problem”.

Same with commenting code and having code reside in Technical Specifications. When you change code you usually comment, but will you go back and ensure the Technical Specification doesn’t reference this exact piece of code and more importantly should you?

In conclusion my suggestions with regard to detailed code descriptions are as follows:
1) Do not include code in the Technical Specification unless its there as a sample or to illustrate naming conventions or something along those generic lines.
2) If you want to document business rules against code do so within the code and then if you need to expose this detail to an audience generate documentation from the source code.



  1. #1 by Ana Nelson on January 9, 2009 - 3:55 pm

    Good post. I’m sure in the near future we’ll have robots who are capable of carrying out the instructions in tailgate-changing manuals, and then the auto manufacturers can run tests of their documentation. We programmers, however, have this ability now and we should be using it. Even putting “just an example” of code into a document isn’t a good idea unless you can execute that example easily to make sure it’s still valid. I’ve used plenty of documentation that looks great, and contains really helpful examples of code… until I try to run them and get error messages because the example was based on an old version of the code. Fortunately there are various literate programming frameworks out there that let you keep your code in runnable files and incorporate them into a document via a scriptable build process, so you can insist that code snippets are run each time your document gets built, and add things like syntax highlighting too. This is particularly important for tutorials or getting-started documentation where your users might not have the confidence to move past a strange error message. [And okay, more likely what will happen with the tailgate-fixing robots is that there will be a DSL for writing a user manual, which on the one hand gets compiled into instructions for robots and on the other hand gets turned into prose for people to read.]

Leave a Reply

Please log in using one of these methods to post your comment: Logo

You are commenting using your 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 )

Google+ photo

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

Connecting to %s

%d bloggers like this: