Standard[ised] Coding

Recently I was handed a piece of code by a client “for my opinion”. A quick glance at the code and I was horrified! This particular piece of code was destined for a SIL0 subsystem of the safety critical embedded system that we were working on. Had it been destined for the more critical SIL2 control subsystem then I would immediately have halted its progress. So what gross indecency had this code committed?  well simply that it contravened the coding standard in place for the project. This got me thinking and I began to reflect on why we used coding standards in the first place.

Coding standards embody the norms and practices of an organisation with regard to programming style, rules and conventions but why have one? Why not allow each software engineer to use their maximum creativity, knowledge and experience to craft software modules?

To answer this question, it’s probably important to look at some of the things that can go wrong whilst writing software. For the sake of this article we will use the ‘C’ programming language. This language is a wonderful bare-bones programming experience giving the engineer flexibility to access the nuances of the hardware. However, there are some real dangers lurking beneath the waves.

By way of an example let’s look at the following:

int mycopy (char *dest, char *src, unsigned int len)
    while (len--)
        *dest++ = *src++;
int count = -1;
mycopy( buffer, source, count );

In this simple piece of code, the parameter ‘count’ would quietly be converted to an unsigned int and since the size of the types are the same the bit representation of the value remains the same (remember minus one is 0xFFFF on a sixteen-bit system). This would make the minus one value effectively a very large positive number in the unsigned ‘len’ parameter. Without doubt this would overrun the target buffer and trash its way through memory. Even though we know this, individuals can easily miss the type difference when writing large amounts of code and utilising modules from others.

Therefore, our coding standard should, as far as possible, prevent us from using constructs or operations in the language that are at risk of causing problems. Ideally we should use tools that automatically draw it to our attention. One such standard is ‘MISRA’ which has existed for many years now and has a multitude of tools available to check adherence to it (and in the case of the client above was actually mandated!).

What such a standard does it to help normalise the skill levels of the members of the team. Experienced engineers who might never make this mistake and junior engineers, who perhaps aren’t even aware of the type of problem, will now produce code with a lower probability of bugs. Any team is only as strong as its weakest link (the most junior engineer) and therefore finding ways for that individual not to make the mistake is well invested time – fewer bugs created at the source of the problem means time and cost savings!

The other area in which coding standards have a huge impact (but also brings the most arguments) is in style and naming conventions. Having a common style is more important than most engineers realise and I argue that this is because of productivity.  I will abstain from the discussion of whitespace other than to say that it is the consistency that is important so that, when reading code, the user can quickly judge blocks of code and should not have to hunt for the closing brace. This is most apparent when utilising another team members code, the ability to find ones’ way around it has a direct impact on the time taken to finish writing code. Common ways of organising and naming elements within the code all help to reduce the “learning and using” time of other people’s code.

Sometimes, coding standards will enshrine good programming principles such as keeping things small, modular, loosely coupled etc. Again, these principles should not be overlooked as they will have a direct bearing on the cost of development (and time to completion). Anything that reduces complexity will speed understanding and reduce the possibility of bugs – all enemies of productivity.

So, with all of these elements making up the coding standard one should expect that, generally speaking, each programmer would produce code that is similar or “standard code”.

The phrase “coding standard” is now a little warn-out, often has negative connotations OR is often overlooked. Using the phrase “Standard[ised] Coding”, I think, aptly describes the reason why we have these documents – not to restrict the flair, creativity and productivity of engineers but to ensure we get a consistent output from everyone who comes into contact with the code. This in time will save money and project duration which, in my book, is something that businesses should constantly strive for in order to be successful.

Finally, the biggest benefit of “Standardised code” is the maintainability of the software. Software lasts for a very long time and frequently the developers are not responsible for its maintenance. Having software that is consistent throughout will allow it to be far easier to maintain in the future for the engineers who will be responsible for corrective maintenance and feature enhancements.

So what about the piece of code that I “reviewed”? Well this will now have to be rewritten to comply to the standards that do exist in the client’s organisation. The code is riddled with the types of errors indicated above and is in a style totally different from that produced by any other engineer. Sadly, this will cost time for the project which will have an impact at a later date – not ideal.