An in-depth guide of how to create, test, apply and maintain coding standards.
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. Tight deadline, our case is too special, or bad management. Results are delays, overtimes, reoccurring bugs, stresses, and failed projects.
Luckily, there are teams which does pretty well. They are writing pretty 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 to you 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.
This is hard work and at the same time necessary for success. Good news is that once you make the preparation, then you have your personal asset which you can reuse for years. I am successfully using the same standards, with updates, again and again for more than 6 years.
The main goals for preparation are the following.
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 the word, google docs, or even plain text editor. I personally prefer Notepad++ and use 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 3 main topics.
Be imperative. You are defining standards and expecting other people to follow them. Say it straight and in a 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. Chance is that someone will start complaining. Then 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. For example this one.
Keep it short, under 100 pages. If your standards have 300 pages, then most people won't be able to even read them. And then it's 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 reasonable good. An example of the priority is a safe code with guaranteed low amounts 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 ever microsecond is counted.
Don't waste real estate on things which can be automated. For example 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 a "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 less language features you need to cover, the easier 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. You don's want to entertain, be super polite or sexually neutral. 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 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.
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.
And one more important point. The whole point of the standards is to create the long term benefit for the whole team, comparing to the situation without them. 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 standards. More is better. The bare minimum should be approximately equivalent of 1-month full-time work.
While doing this, watch for these points.
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 4 months to produce a useful version.
If you can clearly answer no to all these questions, then congratulation!
Now you have the following.
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.
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.
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.
Strategy 1 - 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. Strongly shutdown any attempt to break any priority point. If you don't know what to answer, then the universal answer is that you are the boss and you have the responsibility for that decision. Don't use this too often. In the end, ask everyone for the commitment.
Strategy 2 - follow for new code and update on touch. 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. Same as in strategy 1. Be ready for the questions, and ask everyone for the commitment in the end.
Strategy 3 - grow 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 it's an opportunity to step out of the crowd. By the way, 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.
Strategy 4 - 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.
Strategy 5 - don't ask for permission. This involves some risk, so be ready for the case it won'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.
Strategy 6 - wait for another opportunity. Hopefully, the reason is the project is going really well and there is no point to change anything. Therefore instead of introducing anything brand new standards, you can improve the existing ones and grow up on it. 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. I know this sucks, regardless of the reason behind. 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.
The whole work up to now is useful only if you can benefit out of it for a long time. In order to do this, there are 2 things to care about. Make sure that rules are not fading out, and make sure they stay actual.
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.
Some background. Common project layout is that people are committing to the repository (to understand the following text, you will need some knowledge about Mercurial or Git). 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 3 groups, based on the way how the merge is done.
How to write a list of things to change. Make it simple, just location and comments. For example this way.
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 in the formal way, so you can track the difference between in code quality between the reviews. Over time, this list should shrink significantly and shouldn't contain any priority point.
Finally, it's good to know when to stop. Wasting too much time on a minor stylish issue which has nothing to do with the actual quality of work is not good. So tolerate that 1% (these are that extra rules you prepared up front). People are not robots.
Time to time you might get into the situation when you have to make a decision whether to make an exception or not. And here I mean that type of exception which breaks one of the important rules. Here is how to handle this.
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.
This is the best. If you can, give the candidate your standards to read and then let him write a little bit of code following that. You will quickly know whether he is capable and willing to code according to it. If yes, then you can invite him for the interview. During the interview, cover the topic of the company standards and ask him to respect that. If he says yes, then you just made a great deal.
Updates and improvements are the nature of every living product, coding standards are the same. Therefore I recommend to constantly looking for ways how to make things better.
Tip: Good candidates are the ways which reduces the amount of code while keeping quality.
Before you do an update. Realize that you already have a solid base. Don't rush for an update.
Test first. Every update can be tested in the separate project, or at least in the 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 spread this across everything.
Making 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.
Having quality coding standards in place is really a great investment. You need to make 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. Words like thank you, reasonable praising, and time to time nice surprises to your teammates are helping to make a nice environment.
Just do it, and enjoy your life!