Many teams and companies are terrible at following coding standards. Then the code is written in a messy way, without meaningful tests, and nobody even thinks about the documentation.

Excuses are always the same: a tight deadline, unique situations, or bad management. The results are delays, overtimes, reoccurring bugs, stresses, and failed projects.

Luckily, there are teams which do pretty well. They are writing good code with a lot of bulletproof unit test, and awesome documentation. And they can do that only because every team member works in the same style. They follow the coding standards. I know this doesn't sound sexy, but it works.

Therefore, in this article, I am going to explain how to prepare, actually use, and maintain coding standards.

This text is mainly intended for senior developers and team leaders. It might take you several months to go through all phases.

Preparation

This is hard work and at the same time, necessary for success. The good news is that once you make the preparation, then you have your personal asset which you can reuse for years.

I have been successfully using the same standards, with updates, again and again for more than 6 years.

The main goals for preparation are:

• Make your standards great.
• Remove every possible excuse to not follow them.
• Get ready to defend them.

Write It Down

If it's not in writing, then it doesn't exist.

Start with writing down everything you have in your head. A form doesn't matter. You can start in Microsoft Word, Google Docs, or even a plain text editor.

I personally prefer Notepad++ and Pandoc markdown syntax for this type of texts. If you have never done this before, then you will discover that it takes time to tidy things up. Let me give you some tips for writing.

Start with these three main topics:

• How to code
• How to test
• How to document

Be imperative. You are defining standards and expecting other people to follow them, so be sure to say it in a straightforward and clear way. One way to do this is by boxes with rules. Like this one.

Add extra rules for negotiation. This will be especially useful if you want to apply the standards to the existing team. There is always a chance that someone will start complaining, which is when you can use such rules for negotiation.

Include a lot of examples. When you make an example, make sure they always comply with your text.

Keep it short, preferably under 100 pages. If your standards have 300 pages, then most people won't be able to even read them, which means it's then impossible to ask anyone to understand and follow such text.

Focus on priority. Choose that, and structure rules for that. Everything else needs to be just reasonably good. An example of a priority is a safe code with a guaranteed low amount of bugs. Speed, memory optimization, or code compactness are not a priority (as long as they are good enough).

This is suitable for projects with very complicated logic, where other factors can be solved by scaling up the environment. Another example is the super low latency code. Direct access to the array has more priority than code safety.

This is suitable for real-time processing on the embedded devices, where every microsecond counts.

Don't waste real estate on things which can be automated, like code formatting. There is no need to write down the details about every bracket. This can be done automatically by IDE.

Therefore, in your standards, make a single rule specifying what is considered as "proper" and make an export of such rules. Then attach it to the standards so other people can just import it in their IDE. Following an example of the formatting rule.

Use minimal language syntax to reach your goal. Coding standards are not a textbook to teach programming language. The fewer language features you need to cover, the easier it is for the reader to understand and follow.

In fact, it is good to prohibit some patterns or language features by rules.

Make it easy to read. This is easy to say, and hard to do. Just realize that you are not writing a novel.

The purpose is to make sure everyone can understand and follow the text. And if you have some money to spend, then it's worth to let a professional editor to help you.

Finally, if you are working with Java, or just want to have an inspiration, then Robust Java Standards might be a good fit for you. I have put serious effort and many years of coding, testing, and team leading experience into this book. And these are the actual standards I am using on a daily basis.

Testing

You have written everything. This means you are ahead of most other people.

The next step is to verify that you can follow your standards easily and that they cover everything you need. You need to master your own standards.

The whole point of standards is to create a long-term benefit for the whole team. When you finish testing, you have to be truly sure that this is the case. And you have to be able to explain why. If you can't do that, then get back to the writing phase and improve.

The best way to start testing is by writing a private side project. It's all about writing a big volume of various code exactly according to the same standards. More is better. The bare minimum should be approximately the equivalent of one month of full-time work.

While doing this, watch for these points.

• Do you need to break any rule to reach a goal?
• Is there any unacceptable hit caused by standards (e.g. performance, memory or logical)?
• Is there any rule which is already bothering you?

If you answer yes to any of these questions, then get back to the writing phase, tweak it, and do the testing again. Seriously, it would be a miracle if you make everything perfect on the first shot. Feel free to make a number of iterations here. In my case, it took roughly four months to produce a useful version.

If you can clearly answer no to all these questions, then congratulations!

Now you have a tested text with standards, and you are sure that the team as a whole will benefit from it and you can clearly explain why.

Therefore you are confident to use the standards in real projects and stand behind. Once someone will try to put them down (this will happen sooner or later), then you will be able to defend.

Provide Easy Access

Readers need to have easy access. Otherwise, this could be a good excuse. The simplest way is to share the link within the company system or tools like google docs.

Once you are done with all these, then you are ready for the next phase.

Application

This phase really depends on the situation you are in. The best case is that you are starting a new project as the leader. Here, I will present several strategies.

Then you will need to adjust and combine them to fit into your situation. If you are creative and hardworking enough, then sooner or later you will be able to have your standards in place.

Enforce from the beginning. This strategy works if you are on the leading position and project is at the beginning. Set up a meeting, walk through the standards and ask everybody in the team to follow that.

Be ready for the questions, but be firm against any attempt to break any priority point. In the end, ask everyone for the commitment.

Update older code to follow the new guidelines. This strategy is helpful when you are a team leader of the running project. Call a meeting, and walk through the standards.

Then ask everyone to write new code to comply with that and update any portion they touch to the standards. Be ready for the questions, and ask everyone for the commitment in the end.

Build it up. This strategy is suitable when you are a regular team member, and for this particular case, it's actually even better when the project is struggling.

Understand that's a bad situation, but that it's also an opportunity to step out of the crowd. That's how I applied my own standards for the first time. Start by finding the isolated part of the code and taking exclusive ownership; a smaller portion is better.

Then make the change. This should, after an initial investment, save a portion of your time. Then just do it again and again, until other people start recognizing you. Then you have an open door to scale up.

Rewrite all. This is suitable when you are the leader, or your standards get recognized as a better way of coding. Here you take the whole project and transform it into the form which complies with standards. Many times this is the final step after you start with strategy 2 or 3.

Don't ask for permission. This involves some risk, so be ready in case it doesn't work out. The advantage is that you can do this anytime unless there is a gatekeeper who is constantly reviewing your work.

Simply write your code according to the standards, without asking anyone for permission, and take it as a normal way you work. Do it until you get to the conflict with someone else.

Then this is the time to put on the table what you have and prove that it's for the benefit of the whole team. Now it's about the conflict resolution.

Wait for another opportunity. Hopefully, the project is going really well and there is no point to change anything. Therefore instead of introducing brand new standards, you can improve the existing ones and scale them up.

That's pretty good because you can build up your track record and use the knowledge for your next big thing. The other extreme might be that leadership shuts down any effort for improvement while the project is struggling. In such a case, it's better to minimize your effort on this ship and look for another opportunity.

Regardless of the strategy choice, you can consider this phase as successful as soon as some reasonable piece of the product is written according to your rules.

And other people must respect that. You don't necessarily need to be their boss. But you need to have a definite word about that concrete part.

If you have that, then you are ready for further expansion. And it makes sense for you to go for the next phase.

Long-Term Maintenance

All the work up to now is useful only if you can benefit from it for a long time.

In order to do this, make sure that the rules are being followed as they were originally prescribed and that they are being used consistently.

Code Reviews

Code reviews are the primary instrument for making sure the rules are being followed. Naturally, this requires more effort at the beginning, which gradually decreases when people are learning.

A common project layout is that people are committing to the repository. These repositories support branches, where people are typically making their commits. Later branches are merged into the main branch as a set of commits which implement the particular request.

I prefer to separate people into three groups, based on the way how the merge is done.

1. People who are verified and doing great. They can merge to the main branch without asking. Typically, these are people I work with for a long time and we have mutual trust.
2. People who need guidance. They need to ask for approval before merging. I review the code and give them permission, or list of things to change, then repeat the process until necessary. Eventually, these people will move to the more reliable t. This setup is typical for people who are new in the team.
3. Those whose code always needs to be reviewed. I use the repository set up which prevents these people from automatically merging. Then do the same review as #2 and merge on my own (or ask someone from the previous groups). This setup is handy for vendor partners when I don't know who is doing the actual work, as these people might switch very often.

If you do have some review comments that you need to make, make them simple, noting just the location and comments. For example:

• UserService - line 54 - input parameter XYZ cannot be used in the interface
• Account, Car - consistency validation is missing
• Account - line 123 - getter returns an unsafe object which might cause the side effect, make the defence copy or return it with an unmodifiable wrapper

If the list is long, or some priority points are there, then it's a good practice to walk through it with the person who is doing the work.

And in some cases it makes sense to make this formal, so you can track the difference in code quality between the reviews. Over time, this list should shrink significantly and shouldn't contain any missing priority points.

Finally, it's good to know when to stop. Wasting too much time on a minor styling issue which has nothing to do with the actual quality of work. So tolerate that 1%; people are not robots.

Making Exceptions

From time to time you might get into a situation when you have to make a decision about whether to make an exception or not, one which breaks one of the important rules. Here is how to handle this.

1. Allow some significant amount of time to think about it. Never allow an exception right away.
2. Try on your own to figure out how to satisfy the goal while keeping the standards in place.
3. If you succeed, then the answer is no and you need to support it with your solution.
4. If you can't do it, then figure out the minimal possible break of standards and allow just this in that particular case. Nothing more.

And remember, making an exception should happen very rarely. If you are thinking about making an exception once a month or so, then there is something wrong with the standards.

Hiring Process

When hiring candidates, if you can, give the candidate your standards to read and then let him or her write a little bit of code following that. You will quickly see whether they are capable and willing to code according to it.

If so, then you can invite him or her for the interview. During the interview, cover the topic of the company standards and ask them to respect that.

Updates and Improvements

Updates and improvements are the nature of every living product; coding standards are no exception. Therefore, I recommend to constantly look for ways to make things better, and remember these tips.

• Good candidates are the best ways to reduce code length while keeping quality.
• Before you do an update, realize that you already have a solid base. Don't rush to update.
• Test first. Every update can be tested in a separate project, or at least in a limited scope. If the update turns out to be bad, then it's easy to rollback. On the other hand, if the update turns out to be good, then you are ready to deploy it.
• When making an update, first, write it down. Then announce the update. During the announcement, demonstrate the new update and ask everyone to write new code according to that, and update the old code when a particular part is touched. You might do that by email or in person. In the end, ask for everyone to confirm the message.

Conclusion

Having quality coding standards in place is really a great investment. You need to do the hard work at the beginning, and then you can live from that for years.

While protecting all the rules, please stay human and be grateful for the people who are working hard. Showing gratitude to your teammates maintains a great working environment.

This article originally appeared here.