Over my last months doing contract programming I’ve seen a lot of code that has very little documentation or formal testing. The method of running successful projects has involved having competent programmers, consistent project management and good client communication. Most of these projects are for small companies who are new or just starting to take off, and I heard a lot of “I don’t think they’ll want pay for unit testing,” or “I don’t think they’ll pay for a 40-hour documentation run.” This is true in most cases, and the logic behind it is backwards.

There are a lot of predictions that one can make based on the size of a company. Smaller companies have a higher expected rate of return, since their smaller size increases the risk associated with any project. Along with that higher expected rate of return is a sharper decline in the future value of money compared to the current value of money, and by extension a sharper decline in the value of future effort compared to effort now. This kind of thinking makes smaller companies more inclined to not clear 40 man-hours to document a code base, knowing that in a year, when they expect to need to bring on another 10 programmers to handle the growing development load, it will cost well over 40 man-hours to bring them up to speed. Additionally, that documentation would save time when designing new features by clarifying the ways the new features must interact with existing ones. The same goes with unit testing, which has an up-front cost but saves a lot of time once things are being added: not only does it provide yet more documentation of the expected behaviour, it provides free regression testing once the change requests start flowing in. These are investments that keep on returning: they will save developer time for the entire length of the project.

Now, there’s a terrible thing that can happen in a software project, which I’ll call the “Oh, Shit” Moment (OSM). This is the moment where one realises that one’s code base is incapable of supporting a change request or important new feature without considerable rework, or the moment the senior-most members of one’s team start spewing profanity and quit. These moments happen often in the real world, especially with small companies where the scope of the software isn’t well defined. For a small software company, an OSM can mean something as small as a few dozen unplanned programmer hours (ie, a few thousand dollars), or it could mean abandoning a significant amount of new code due to unexpectedly high integration cost, or it could mean a huge rewrite and possibly the end of the company. So how do testing and documentation affect OSMs?

• No matter how readable one’s code is, design documentation is always more readable. This helps new developers come up to speed quickly and saves existing developers time when they use code that has lain untouched for months or years. This can both prevent and diminish the impact of an OSM.
• When a bad design decision has been made, it tends to become much more obvious when one tries to explain it in plain language (and for some reason needs a thousand words); this can prevent some OSMs from ever happening.
• A module which needs to be rewritten can avoid re-integration problems much more easily if there is a unit testing framework, or at least a well-documented interface that it must adhere to. This will considerably reduce the impact of the OSM.
• Unit tests created as bug-fixes from the original version are documented summaries of things to be careful of the next time around.
• Documentation provides a clearer overall picture of the project, which will significantly aid decisions which must be made about the design and implementation of a module which must be rewritten. This and the last point can turn an OSM today into a blessing in the future.
• Documentation will help when it comes to estimating the development and integration cost of new features, which will help prioritize new features as well as see OSMs on the horizon.

Smaller companies may not have more to gain from keeping good development practises than large companies, but they have a lot more to lose. If a project at IBM fails, IBM shrugs, writes it off and continues being an enormous and generally profitable company. If a project at a small company fails, it means a significant financial loss, if not the loss of their entire ability to generate new revenue. We want to keep that rate of return high, and it’s worth that little extra investment up front. Really.

This entry was posted on Sunday, December 16th, 2007 at 11:45 pm and is filed under Software. You can follow any responses to this entry through the RSS 2.0 feed. You can leave a response, or trackback from your own site.