Developing a company coding standard is absolutely critical to ensuring that every embedded developer is on the same page. A coding standard tells a developer many of the do’s and don’ts that they need in order to write legible, reviewable software that achieves the businesses desired quality level with the least number of defects possible. I’ve reviewed and written several dozen coding standards in my career and the ones that seem to generate the best results typically have the seven sections that we are going to explore in today’s blog.
Section #1 – Scope
Defining the scope that the company standard will cover is really important and often overlooked. I see lots of standards that include a purpose, but frankly, why the standard exists is not nearly as important as the standards scope. The scope tells the reader what it is that the standard is planning to cover and who it applies to! Is the standard just for C developers writing microcontroller applications or does it also include developers writing Linux applications or doing Linux kernel work? Does the standard apply to only new code developed or does the standard need to be applied to legacy code? Does it cover third party library code as well? The scope lays the foundation for the rest of the standard and who it is that should continue reading and then implementing it.
Section #2 – Verification
The second section that I like to include in a coding standard are recommendations for how the standard will be verified. I sometimes see coding standards used like a business plan; a ton of time and effort goes into writing it, but once it’s completed, it goes on a shelf and isn’t ever referred to again. This is why I think it’s important to tell the reader how the standard should be verified.
There are many different ways that a coding standard can be verified. These often include a combination of code reviews and static code analysis. A good standard should be automatically verified with a tool but that is not always possible. I also find that it is useful to comment on when it is recommended for a developer to verify the standard. For example, should a developer verify the standard before they commit their code, during the commit as part of a continuous integration process? Only at release? These are questions that are often covered by a company’s development process that could change, so I often include recommendations, but then leave flexibility for that process to do what makes the most sense.
Section #3 – External References
Embedded programming languages such as C have been around for half a century. There is no reason to start developing a standard from scratch! This is why I believe third section in any company coding standard should be to identify external references that should be followed and adhered to. For example, a company might reference industry standards such as MISRA-C or CERT-C and then lay out the expectations for which directives should be followed and which ones can be ignored. These external references allow the standard to build on the foundations that have been laid out by industry and can simplify the work required to put together a company standard.
Section #4 – C Style Guidelines
Nearly every developer has their own way of styling their C code. The C Style Guidelines section is perhaps the most important section to ensure that the code base under development has a consistent look and feel to it. This is the section that lays out important guidelines such as:
- Spacing
- Parenthesis placement
- C keywords that are allowed
- C keywords that are avoided
- How comment blocks should look
- Naming conventions
- Etc
If developers all adhere to the C style, it should be nearly impossible to determine who wrote the code because every module should look the same!
Section #5 – Projects
I’ve also found that it’s useful to lay-out recommendations on how a project should be organized. For example, this section can discuss areas such as:
- Versioning the software
- How to organize the software layers and modules
- Recommended hardware abstraction layers such as CMSIS
- How to handle interrupt service routines, the stack, heap and memory management
- Recommendations for integrating third party components.
- etc
Including these details can also make sure that every project the team works on is consistent and it’s easy for a developer to move from one project to the next.
Section #6 – Hardware / Compiler Specific Features
There are also recommendations that developers need for interfacing to hardware and using the compiler. For example, this section can outline whether #pragma can be used and if so, what directives are allowed. (Granted this is compiler specific so a change in compiler means a change in the standard, so an external reference document might make more sense). This section can also demonstrate preferred methods for interfacing to hardware registers and interrupts. For example, directly accessing registering, accessing through a pointer mechanism or using a pointer configuration structure. Anything related to hardware and the compiler would be documented here.
Section #7 – Appendices
Appendices can contain a wealth of information that is important to a developer but doesn’t necessarily belong in the rest of the coding standard. For example, a team might include an appendix that defines a “Glossary of Terms” so that any new developers to the company can learn the terminology that is used within the company but may not necessarily be an industry recognized term. Keeping track of this type of information can ensure that everything a coder needs is in one place so that they don’t need to waste time hunting for it if they need to reference it.
Conclusions
A company coding standard is an important document that every development team should have. These documents lay the foundations from which a project is implemented and can dramatically affect a code bases quality. If you have a coding standard, you should review it at least once a year to make sure that it’s guidance still makes sense. If you don’t have a coding standard, you can start by using this blogs suggested sections as the outline for a standard document that you update once a month until you have a fully documented coding standard. If that’s not fast enough, feel free to reach out to me at [email protected] and I will provide you some options on how to accelerate your company coding standard development.
