On Code Documentation or How to find your way Around a Resort

Having up to date and relevant documentation is a challenge for any software maintenance team. The key to success is to write a minimum of documentation, but make sure that it is relevant. The details can always be sorted out from the code. The external documentation (that is not in the code) should focus on being a good introduction by giving an overview.

The documentation should point in the right direction to get started working with the code base and show what modules there are. It is a bit like when first arriving at a resort. You’d expect a map and some directional signs to use until you’ve got to know your way around the area.

Before going into how it looks like, let’s consider how it would be if the resort was documented the way most code is.

The instructions where clear: “Drive 24.7 km on the main road north, then take off to the right”.

The trip meter now is on 24.7 km. It is dark. No street lights to be seen anywhere close. No signs. No road to the right. Nothing but a trail of mud and sand between the dark trees. Well this is where it should be, so you take to the right.

The ride is bumpy but it is clear that cars regularly drive here. Suddenly the mud and sand is replace by a proper concrete road. The forest leaves place for a beautiful view of the large, luxurious resort close to a moonlit lake. You park the car among the other cars (although there is no parking sign, but it must be here) and head off towards the main building.

You find a closed door. There is a well used path in the grass around the corner so you follow it, just to end up on a small beach, still carrying your luggage. Going back you see a door which is open and head over there. It is the restaurant, but at least you find a waiter that can show you the way to the reception.

The receptionist is nice and your check in is processed quickly. You get the keys and head over to the elevator. Once inside you check for the right floor for your room number which is: D7BC. There is no D on the panel. Just plain numbers 1-15. Before you can decide what to do the elevator moves on to floor 7 where a family is waiting to get in the elevator. You get off to leave room and have time to think.

Think this is ridiculous? Unfortunately this is the very same feeling that I far too often get when first looking at a new code base. I’m not finished yet, there’s more to come…

The corridors look endless. Looking closely at the door in front of you there is a small engravement on the lock “D77C”. Looks pretty close. You check the next door. “D67C”. The door to the other side is “D87C”. Behind the elevators is a passage to another corridor where you find “D77D”, “D67D” and “D87D”. So close, but your room is not here…

Just before you’re about to give up, one of the hotel staff appears and helps you find your room at floor 11.

Finally inside the room you are surprised to see a sign over the bed:

Put your head on the pillow, pull the blanket over you and sleep.

After the struggle to get here you don’t need instructions on how to sleep. Exhausted you fall asleep before the head even hits the pillow.

That’s not really a good first impression of a luxurious resort. It doesn’t matter if the food is world class, the weather perfect and the spa facilities excellent if the first impression is so bad.

Unfortunately that is exactly how many code bases look. The bumpy trail of mud and sand is the process of getting the source to build. The lack of signs is the lack of overall documentation on where to start. The key numbering is perfectly clear once you understand it (1 digit floor, 1 digit corridor, two digits room number, all stored in little endian hexadecimal), but completely confusing until you get the explanation. Ohh, and the sign above the bed is just like all those redundant comments pointing out what is already obvious by the line of code below the comment.

This is not how it should look like. Thinking like the owner of a resort a minimum set of documentation can satisfy new guests’, ehhmm, sorry developers’ needs.

Build Documentation

The very first impression of your code is actually not the code, but the build process. You don’t want it to be like a dark bumpy ride in the mud and sand. It should be very clearly documented with a simple step by step procedure on how to get it running on a new, clean machine. State clearly what components are needed and where to get them. Include setup instructions of components if necessary. You don’t want the build to be so complicated that people give up.

Architectural Overview

Once a new developer can build the software it’s time to look at the code. This is when an overall map is needed. A simple sketch of the general application blocks and where they are located in the source tree is usually enough.

In Code Documentation

The in code documentation is often superfluous. Don’t comment stuff that is evident from the code. If the intention is not evident, fix the naming of the things in the code until the intention is evident. Keep the in code documentation to a minimum, I usually only do the XML comments for intellisense. They make sense as they show up when a function is called, without looking at actual code of the function.

Keep Documentation High Level

The key to successful documentation is to keep it high level. It should help a new developer to learn the big picture of the code’s structure. It should point out what code to start reading and how that code is related to the rest.

Keeping the documentation high level won’t only make it more useful, it will also be a lot less to write and maintain. High level documentation also tends to be more stable requiring fewer updates. Producing better documentation in less time with less need for updates to it saves more time for coding.

Documentation is part of the software development job. Coding is a passion.

I’d rather spend my time coding than writing documents.


  1. Documentation for what?

    End user documentation is something programmers shouldn’t do, because the skillset required to develop good user documentation has not much in common with the skillset of a programmer.

    If developers need documentation for some piece of code, that piece of code is crap, and should be refactored until it becomes readable. The effort spent initially on refactoring will pay off tenfold or more later on, during maintenance.

    IMO, the only case for technical documentation is a closed source web service or library.

    I’m not aware of any compiler or documentation tool that can check documentation correctness. Any piece of documentation is a source of trouble, since it easily becomes outdated, without automatic means of verification. Therefore, the code itself should be regarded as documentation. If code isn’t readable, that’s bad documentation.

    As for the initial example, it sounds more like bad API design to me than bad documentation. One more reason to avoid documentation – good and well maintained documentation might actually hide problems in code.

Leave a comment

Your email address will not be published. Required fields are marked *

This site uses Akismet to reduce spam. Learn how your comment data is processed.