December 7, 2012

Be the Change You Wish to See in Your Codebase

If you've ever worked with other developers on a project you know that writing consistent code across the entire team can be difficult to achieve without some thought and planning. More importantly, however, it is impossible to achieve consistent coding practices across a team without consistent execution of those practices.

In the software engineering management world there's a lot of talk about team software process and how it's easier and better to integrate teams of engineers when there are documented standards and practices in place. However, the focus there seems to be on the documentation of standards and practices rather than the execution of the same. The thinking seems to be that if a process is documented it will be followed, but I am not convinced that is really the case.

I've worked on several different teams in different verticals over the last 5 years, all of which had varying degrees of documentation of standards and practices for product construction. What I've found is that documented standards and practices were only followed by new team members coincidentally regardless of the level of detail or quality of a standards document, and regardless of how ardently management advocated for following such a document. Instead, new team members simply adopted whatever practices were implemented by existing team members. What's more, if there was a question as to how to approach a specific situation, a new team member would not consult documentation. Rather, he or she would ask a more senior team member what to do.

Of course, there's nothing wrong with peer training on standards and practices in principal. I would always rather ask a coworker what to do than read some Word document that probably hasn't been updated since the days of Clippy. But, if the practices implemented by existing members of a team are inconsistent with one another and the documentation, then there is no hope that any standard will ever be followed (regardless of whether there is documentation or not).

The interesting side effect is that every so often the old guard of the team will bemoan the mess that the codebase has become, seemingly unaware of the fact that they have created the mess themselves by employing practices that are inconsistent with one another and inconsistent with the documentation. The conclusion reached by existing members of the team, however, is almost always that someone else isn't following the documented standards, or the documented standards need to be updated, or some sort of training program needs to be put in place, etc.

While all of these proposed solutions may be of some benefit, they do not address the real problems: the existing codebase and the inconsistent practices of existing team members. And, to the team's (and management's) dismay, nothing gets better. Team members come and go, and over time the inconsistent practices actually grow worse. Eventually the codebase becomes an incomprehensible mess, and there are cries to tear it all down and start over again with a new codebase, new standards, and (of course) new documentation.

And so the cycle repeats.

How do we avoid it? It almost seems impossible, but it's not. It's not easy, of course, to avoid inconsistent coding practices. It takes time and discipline. A lot of discipline. Almost militant discipline. Nevertheless, it can be done. The key factor - what you need to remember at all times - is that as a manager you need to focus on what your team is doing, not on the documentation, because most of the time no one's going to read the documentation.

First, you need to sit down with your team (or core members of the team) to figure out what the standards and practices should be in the first place. It is absolutely key that everyone buys in, so it's better to have few standards that everyone agrees to at first than it is to have many standards that not everyone agrees to. If you don't already have documented standards, start with some things that are easy to implement but will have great benefits (a consistent directory structure for all projects, for example).

Second, you and your team need to refactor existing code under development and/or test to meet the standards that you've all agreed upon. This has to be done regardless of the extent of the effort required. It will be worth it in the end, I promise.

Third, and most importantly, you and your team need to implement the agreed upon standards in all new work products it creates, without any exceptions.

Finally, you and your team should document the standards you've implemented, but you should do it in two forms: a requirements document and a technical spec (you'll see why in a minute).

The future is bright...

The great benefit of having a documented standard that is actually applied in your codebase is not just that your codebase is consistent, rather it is what you can do with your documented standards to make your codebase work for you. You can create tools to automate repetitive parts of your code to remove inconsistencies due to human action. You can create tools to measure logical SLOC, which will inform many other processes. You can create a code analysis engine using the technical spec to make sure that your codebase remains consistent over time. You get the idea.

Moreover, when team members come and go you will have the most powerful and most valuable documentation and knowledge transfer system available: your codebase.

1 comment:

Nick Viper said...

I agree with everything mentioned, however there is a quote missing that pretty much sums everything up: Trust, but verify.

While all standars should be documented for new people and CYA, it is absolutely true that most simply will not be bothered to read or follow them. I work with a team of about 15 developers, and my role in this team is to enforce those standards and practices (whether written or not) for everyone's benefit. One of the greatest tools I've found for this is to subscribe to check-in events in our TFS server. Everytime someone checks in code, I spend a few seconds briefly looking at the changes, and schedule follow up reviews as they become necessary.

Obviously this advice only applies to teams using TFS, but I'm sure a similar feature exists in most source control packages. I can't tell you how opaque and shady some developers will get to avoid a thorough, transparent code review but you can't hide from the source control engine!