Some of my clients put their best software developers on a project to build a system and then afterwards they put new hires on to maintain and extend it. Often the intention behind the original design is not clear to the people who have inherited the system and so they tend to make changes that degrade the overall quality of the system, ending up with code that is difficult to work with.
Unfortunately, the fact that your business is successful means it probably has legacy code that is rotting away. Code rot is real (see post Is Your Legacy Code Rotting?). I don’t mean that bits get corrupted. In fact, software is one of the few things in the world that does not change and therein is the problem.
Everything else but code changes: requirements, teams, needs, etc. so relative to the rest of the world code appears to rot. It happens as developers hack in special case handlers instead of working to extend the system through refactoring and redesign, and this is all too common.
We have a fear of changing legacy code and as soon as we fear changing a particular piece of code, we are in the downward spiral of code rot. As code rots, it is harder and harder to make changes until it becomes cheaper to throw it out and start over.
We can’t continue to build software in this way. If we want our software to continue to provide value then we must pay attention to the entire software lifecycle and build code to be changeable. We have to find ways to convey why we make design decisions as well as what these decisions are so that the people who maintain a system can understand how to extend it without degrading it.
One thing I like to do at the end of a project to help document why and how we built a system the way we did, is to bring a video camera (and some beer) to our project wrap up party and interview everyone on the team. I ask each developer what they are most proud of and least proud of on the project, what they would change if they could, and why they did what they did. I try to capture the personality of the developer as well as some technical details.
When I show these videos to the people who are charged with maintaining the system they often tell me they learned more about the system from that short video then from reading all the written documentation and source code.
Of course, it is not one thing or the other; we can have both the standard documentation and an interview of the team on video to draw upon. Getting a sense of the people behind a system helps those who must maintain that system to better understand the motives behind the design, feel more like they are part of the team, and respect the work of the original developers.