Code archaeology

Something interesting happened today. For a couple of years, myself and colleagues had mulled over a certain 'killer feature' that we wished our networking layer had, as it would have made our time implementing gameplay features much easier. Today, while doing some long awaited R+D work on said layer, I found that feature. The sheer size of the codebase meant that what we'd wanted for years had lain dormant and undiscovered all that time.

In actual fact, its only call site was commented out with a note saying that it was too slow to use in practice, but I have a feeling that it could have been easily optimised and saved us man-months of work.

Why hadn't we found this before? Well, it's a very large code-base and most of the people who originally developed it are long gone. Unfortunately there was obviously not much time for (or interest in) documentation back when it was written, and we're too busy making actual games to be able to invest time in checking all these low level components which already work.

I see a couple of lessons in this:

• Enforce documentation as company/team policy. When the brains behind the code are no longer at the company, that's when you need documentation to replace that lost knowledge. Unfortunately it's too late to write it then. Designate a proportion of a coder's time to documenting their code, so that an equal or greater proportion of some future coder's time can be saved. (Failure to do this also results in scheduling problems, where some future coder is expected to perform a task as quickly as the original coder did, despite lacking the insight into the code that the first person benefited from.) I know it's hard to sell documentation time to a publisher or whoever, but I'm sure that many projects lose more time from problems that arise when coders don't fully understand the code that they're working with.
• Write less code. Sometimes, documentation just isn't going to happen, or is inadequate, or whatever. One way to mitigate this is to write fewer lines of code. The fewer lines of code you have, the less likely it is that there are large areas of the codebase that nobody looks at or understands. It also brings reliability benefits - if you halve the number of lines in your code base, it stands to reason that each file, function, and line gets read twice as often on average, and double the eyes means more of the bugs get spotted. Cutting the lines of code may not be easy to do, but most codebases have some duplication they can lose. In C++ templates and polymorphism can do a lot for you here if you think ahead rather than resorting to copy and paste. If you're lucky enough to move to a higher level language then you get this benefit for free, since most are far more concise than the equivalent C or C++.

There are interesting implications for team size, too. To reduce the risk from lost code knowledge, you ideally want a lot of coders, and to rotate them round several subject areas. This way, knowledge is spread out redundantly and the loss of any one coder should not impact the general understanding of the system. On the other hand, large teams start to incur prohibitive communication costs, where documenting and explaining your modules can end up taking longer than creating them. And rotating people around areas of the code tends to reduce code quality, both through making people less concerned about defects in their code (since they may never have to touch it again), and through not being able to become an expert in a certain area.

You need enough programmers to be able to develop the required system in the timescale available, but too many and you're going to have dark corners of your code base that few will understand and they can actually cost you time. It may be that there is an optimal number of programmers that can work on any given software project. Does it vary according to the programming language in use? Or maybe according to the type of software being developed?