Severity Levels for Coding Standards

Suppose you are working in a software team. Most likely you will have to digest code from others from time to time. And even your own code can become incomprehensible within a couple of months. That's why most engineers only like to write new code. Maintenance, that is something for masochists! No-one likes to reconstruct the strange thoughts that somebody had when writing some funny "loop" or this mystifying extra "if" condition. Because if your assumptions about such horror code are wrong, your changes to it might have disastrous consequences.

severity levels

Unfortunately, about 90% of all the software labor nowadays concerns maintenance. That is the case because we have neglected how to write readable software in the past. One of the tools that can help you with that are coding standards. A coding standard is a document that consists of rules a programmer should follow. They range from "All names should start with a capital letter" to "Make sure that you never divide by zero". Adopting such a coding standard will make your code become more understandable, faster, uniform and more reliable. Maintenance might even become fun!

I don't know whether you have ever seen a coding standard, but examples can be found here, here and here. It is dry stuff and moreover it is a lot... Usually more than 100 rules... Too much to remember. But luckily there are tools that can check your coding standards automatically. Yes! Problem solved. If you have run such a coding standard checker for the first time for your program, it might look like this:

many violations

OK. Maybe this wasn't a good idea after all. It will take ages before we are compliant with our standard! But hey, we are engineers so we are always looking for some kind of solution. Possible ways to deal with this are:

  • Automated fixes. For some rules it is possible to fix their violations automatically. Just one click: gone!
  • Only showing deltas. Some tools have the possibility to show only the violations you have introduced and thus ignoring all the bad stuff that was already in and was written by that guy that has been fired long ago (for obvious reasons)...
  • Severity levels. If you split up your coding standard in smaller parts, you can focus on the most important issues.

Let's have a closer look at the last item, severity levels, today. The others will be discussed in another blog of this series.

What are severity levels all about? Well, some coding standard rules are more important than others. There are ones that are plain "shoot yourself in the foot" errors. But there are also rules that are only advocated by fanatic elite quality zealots. The most important ones are of severity level 1 and next levels are reserved for more pedantic issues. By dividing the large amount of coding standard rules into severity levels, the most important ones can be identified rather easily.

few violations

Ahhhh, this is doable!

You are free to introduce an arbitrary number of severity levels, but I recommend 10 severity levels. Don't push yourself too hard when you doubt whether a rule should be of severity level 5, 6 or 7, just make a choice. You can always adjust it later on. As a guide, I use the following meaning of severity levels to make it easier to group coding standard rules.

Level 1 - Certainly a programming error

Level 2 - Very likely a programming error

Level 3 - Programming pitfall/undesired programming construct/accident waiting to happen

Level 4 - Design issue with high impact on reliability or maintainability

Level 5 - Design issue with low impact on reliability or maintainability

Level 6 - Portability or performance issue or high impact other issue

Level 7 - Comment related issue or medium impact other issue

Level 8 - Naming convention or low impact other issue

Level 9 - Style related issue

Level 10 - Controversial issue or issue with a relatively high false positive rate

Introducing severity levels to your coding standard, makes adhering to (the essence of) the coding standard more manageable. You start by tackling the level 1 issues first and continue from there. Your code will already dramatically improve with all the level 1 issues addressed. Good luck!

Paul Jansen — CEO TIOBE Software — Paul.Jansen@tiobe.com — 27-Aug-2020