Setting standards from scratch

As the ancient Chinese proverb goes:

“The best time to set code standards was 20 years ago. The second best time is now.”

OK, while we’re not talking about the power of compound interest here (which is where this proverb is often used), it is true to say that setting standards as early as possible make life a lot easier down the road.

Setting standards earlier is easier because you may have fewer contributors, and you have much less existing code to bring into line (or deliberately exclude from compliance).

Where there are only one or two people working on a code base, it might feel like unnecessary overhead and bureaucracy to create and enforce standards.

But even two people can spend a surprising amount of time discussing the pros and cons of minor details of formatting.

The process of creating formal standards in a team situation where previously there were none is a great way of practicing your diplomacy skills: skills in influencing, negotiation, presenting an argument, conflict resolution, inclusion and consensus seeking can all be involved.

The big thing I struggled with when I first took this on was to default to making everything a collective decision. I wanted everyone on the team to agree to every little detail. I imagined that there would be some polite disagreements on some things. But then the ‘best’ argument would win and we could move on quickly. That was wishful thinking, it turned out. When you hire smart people they come with a wonderful variety of opinions too.

In reality, even the most ‘trivial’ details of code formatting can foster robust disagreement (tabs vs spaces, semicolons in JavaScript, declaration ordering in CSS). I even feel the need to put ‘trivial’ in quotes here - many would disagree on the triviality of these points.

Pragmatically, you can’t decide every little rule and standard by committee. The return on the investment of everyone’s time is just not worth it.

It’s far better to focus on discussing guidance that has the most impact. As one reader email put it yesterday:

Rather than argue over use of const vs lets for defining variables, we are trying to avoid future ‘gotchas’ or optimization problems before they happen.

Alexandra Hill’s article (and talk) about code reviews contains this chart:

Code standards and design guidelines can be treated in the same way. Items that are low conflict and low reward shouldn’t be up for discussion. It’s better for the team to spend time discussing controversial items that have a big impact on performance, maintainability, accessibility or some other important consideration for your team.

In fact, Alexandra makes this point with another chart (from her talk at Lead Dev London this year):

Those trivial but high-conflict items in the top left can hijack conversations that should be focusing on the top-right quadrant. As many of these things can now be automated away, it’s best just to pick an existing standard with associated open-sourced linting configurations and move on.

Low conflict and low value stuff can either be ignored or included in automations where there are existing implementations.

Low conflict but high value items can be included as guidance for review by the team, but shouldn’t meet much resistance.

And this should leave you with the energy and bandwidth to focus on those controversial but important topics, like progressive enhancement, design patterns, complexity, trade-offs between system constituents and so on.

By their nature, most of the items in here will be guidelines rather than concrete standards. But that’s because they are often complex topics requiring careful consideration of the circumstances.

Once you’ve made your choices (and it may not be a quick process), the next step is to make the a part of how you work.

What’s the most controversial standard or guideline in your organisation?

All the best,

– Jim