How to Agree on a Coding Standard

Agreeing on a coding standard, and on best practices isn’t easy. Still, if you manage to agree on a coding standard, you are one step closer to a consistent codebase.

Consistency helps a lot with readability and maintainability. So, how can we make it easier on teams to agree on a coding standard, including which coding style and which best practices to use?

In this post, I’ll show you my 8 step process, which I also teach in my code review workshops. During this process, we will use the well-established and powerful DACI decision-making framework. You can reuse the framework I outline to make quick group decisions for many other tricky problems or choices.

So, let’s start.

Step 1: Prepare an initial coding standard

The motto is to stand on the shoulders of giants. So, I suggest to start either with your already existing coding standard or if you do not have one, find one that you like and use it as a template.

I advise against creating one from scratch. Also, in this step, please do not worry about individual choices. This initial coding standard is only intended to make sure we have something to work with.

A good starting point is, for example, one of the many Google style guides for specific languages. Similarly, you can find catalogs with best practices like best practices for javascript from W3School.

Step 2: Build the decision-making team

When you use the DACI decision framework, you first have to assign all the roles and responsibilities. DACI stands for Driver, Approver, Contributors, and Informed.

The first role we have to assign is the driver. This person acts as the project leader but has no decision power. This person is responsible to schedule and lead meetings, assign tasks, track the progress, and keep people informed about the process.

This person can also take over creating the initial coding standard and best practices guideline – if you do not have one.

You also have to choose the approver. This person will make the final decision. It’s not recommended to have more than one approver, because DACI is designed for quick decision making.

The majority of the team will act as contributors. Contributors are selected based on their expertise, unique perspective, and experience. Contributors have a critical impact on the decision as they provide the information the decision is based on. Still, while contributors have a say during the discussion phase, they have decision power.

The driver is responsible to select the right contributors. Depending on the team size, the diver can ask the whole team or only a part of the team for their input.

For example, the driver might select a security expert and a senior engineer to make decisions on aspects of the coding standard that influence how to handle user data. For the readability aspect of the coding standard, the driver might select junior and senior engineers, and maintainers to collect input.

Contributors share their knowledge and information about the different choices, with the team.

The driver also has to think about who should be informed about the outcome of the decision-making process. This group of people is called the informed. They play no active role during this process.

Step 3: Decide what needs to be revised

In a group meeting, walk through each of the areas of this initial coding standard. For each point in the standard, you make a quick vote. Does anybody disagree with the choice? If so, circle this particular part, but don’t start discussing it. Then, move on to the next point.

For example, one point might be “Always Declare Local Variables”. Then, through a quick hands vote, the driver sees if anybody disagrees with this point and marks it as “has to be revised” or “ok”.

Step 5: Prepare the discussion document

Now, prepare a document that tracks each point in the coding standard that raised some concerns in the previous meeting. In this document, you track the following:

• Name and Description of the Coding Stanard point under discussion
• Alternative Options. Those represent the different solutions contributors suggest for the coding standard.
• Per Option, leave some space for the contributors to add arguments for and against this option.
• You can also add some space where contributors can list themselves to show that they support or oppose this option.

I illustrated such a document in the picture below. On the left-hand side, you can add the name of the point of the coding standard under discussion as well as a description. On the right, there is space for several alternatives and discussions.

Step 6: Involve the Contributors

Then, you distribute the decision-making document to the contributors. Everybody can give input for each of the points. Contributors can either add new options or comment on already proposed options. As said before, they can also list their names to support or oppose an option.

Let’s have a look at the example illustrated in the picture below. Here you see a discussion about the point in the coding standard saying “Always declaring local variables”. One contributor suggested to remove this point from the coding standard and outlined his arguments. Susan Wise, another contributor, opposes to the removal of this point and highlighted her thoughts. Two more contributors are opposing to the removal.

This activity should be time-boxed. For example, contributors have one day/week or whatever feels right for your team to contribute to this document.

Step 6: Group meeting with the Approver

After the time is up, or no new inputs are made, the team gathers together with the approver. All points are discussed and laid out during a group meeting. It’s a good idea to also timebox this meeting. The driver leads the meeting and makes sure, the most important aspects are covered.

It’s important here that each alternative is quickly presented. But, do not start to argue within this meeting. This meeting isn’t meant to collectively agree. Yes, this is a group decision, because all contributors have a voice. Still, the main point is to give the decision-maker a good overview of the different options and to allow him or her to ask clarification questions.

We will not collectively agree on a coding standard. We collectively give input and form the opinion of the approver. But, the final decision is out of the scope of this meeting.

Step 7: The decision-making

After the meeting, the approval takes some time (a couple of minutes/hours), and then, walks through each of the options and marks the ones that seem the best fit given all the inputs. It’s important that the approver can take isn’t forced to make the decision during the meeting.

Also remember, the approver has the final say. Coding standards are subjective and opinionated by nature. So, this one will neither be the best nor the correct one. But, and this is much more important, it will be one.

Having a clear coding standard helps team to overcome the endless and unproductive discussions during code reviews. It also increases the consistency of the codebase. And this has many benefits. First, team members can easier contribute across teams, as well as improves the maintainability and readability of the codebase.

So, the only thing left to do is for the driver to inform everybody in the informed group about the final coding standard.

The DACI decision-making framework

Before I let you go, let me tell you a bit more about the DACI decision-making framework. Because you can use this framework not only for agreeing on a coding standard but for any tasks where you want to make quick team decisions.

As you saw, DACI’s strength lies in assigning clear roles and responsibilities to each team member. I also suggest timeboxing each activity, so your team reaches a stable state soon.

I illustrated the entire process in the picture below.

Closing words

Agreeing on coding standards can be a stressful activity. It’s often loaded with passionate or even heated discussions. Using a framework helps to get some clarity and structure into that process. In an upcoming post, I’ll show how teams can use an iterative process, to ease the development of a coding standard even further.

Also, have a look at my code review workshop site. During those workshops, I go into much more detail for techniques like this and also cover topics such as how to increase the code review speed or the code review feedback quality.

To stay informed sign-up to my mailing list and benefit from the weekly email I send that’s packed with well research software engineering topics. I’ll also send you my code review e-book as a thank you.

This article first appeared on https://www.michaelagreiler.com/creating-coding-standard/.

Updated on January 15th, 2023