Have you ever put two engineers in a room to discuss the team’s coding style guide, only to leave the meeting with more than three standards? I certainly have. Coding styles for software developers are a little like religion; everyone has one, and theirs is the right one! Over the years, I’ve reviewed and written code for over 190 projects ranging from safety-critical devices to consumer electronic trinkets. I’ve seen what works, what doesn’t, and what leads to disaster.
In this post, I’m going to walk you through what I’ve learned about developing a coding style guide and how to automatically enforce it so that I can save you some time and pain in creating or updating your own.
The Purpose of a Coding Style Guide
The primary purpose of a coding standard is to create readable code that is easy to review and maintain. When all the code looks the same and is readable, it becomes easier to spot issues, errors, and bugs during a code review. Unfortunately, when code is written in different styles, reviewers tend to focus more on the differences in style than on the code. This is how bugs sneak through reviews.
A coding style guide provides consistency to the code so that anyone reviewing the code will think a single developer wrote it. The team could be twelve or fifteen developers deep! The coding style helps promote industry-proven programming practices that increase engineering efficiency.
Leverage White Space Wisely
When you develop a coding style, that style should be readable. You want your team to be able to scroll through the code quickly and understand it easily. A key feature to making code readable is to utilize white space effectively so that changes in blocks, functions, and classes are all evident and easy to see.
In the main frame days, circa the 1960s, screen and printer technology was limited to 80 characters wide. To see everything on a screen and minimize how much paper was used to print the code, developers would use a compact style like the following:
uint8_t MyFunction(uint8_t const Var1,
uint8_t const Var2,
uint8_t const Var3) {
// Do something useful
}The style is similar to what every Computer Science 101 student is taught.
Experts in high-reliability software in embedded systems typically don’t like this style. Instead, they prefer code that looks like the following:
uint8_t MyFunction(uint8_t const Var1,
uint8_t const Var2,
uint8_t const Var3)
{
// Do something useful
}The argument is that you can easily pair the brackets.
You might like this style, or you might like the previous one. The truth is that both are equally valid. They both use the white space to make it easier for someone reviewing the code to see where the code blocks and changes are. The trick is consistently leveraging the white space to make the code easy to read.
What should be included in a Coding Style Guide?
A coding style guide must contain everything developers need to consistently write their code. There is a wide range of categories that you should consider when developing your own coding standard. For example, you should include:
- Formatting Guidelines
- Comment Style
- Project File Management
- Naming Conventions
- Function Management
- Class Guidelines
- Scope Rules
- Language Exceptions
- Fault Management Guidelines
- Memory Management
- Language Feature Guidelines
There is a lot to consider, which may seem overwhelming to you at first. The good news is that there are existing coding style guides that embedded software developers can leverage.
Coding Style Guides and Standards to Inspire You
More coding styles and standards are available online than anyone would care to admit. These standards are excellent, others not so much. Some apply well to embedded software and others to general software engineering. When it comes to coding standards and style guides, I have several recommendations for you.
First, if you want to adopt a style and standard that will help you minimize bugs and improve the robustness and readability of your code, you should adopt the latest MISRA C standard if you write in C or adopt AUTOSAR[1supposeif you write in C++.
Next, if you don’t have an interest in minimizing bugs or maximizing robustness, you can adopt less strict guidelines. By far, the most popular standard to explore is the Google C++ Style Guide. While focused on C++, teams working in C can still adopt many conventions, which can prepare them for transitioning to C++.
An early inspiration for my own C style was Jack Ganssle’s Firmware Development Standard. The standard is still worth taking a look at to get some ideas. Bjarne Stroustrup also has a C++ Style FAQ which is full of great ideas.
Finally, while not necessarily a standard, I would recommend adopting a clean coding mindset. Bob Martin has a fantastic book entitled Clean Code, which has many practical tips for writing software that is clean, human-readable, and easy to maintain.
How to Verify Coding Style Guide Compliance
When you put together your Coding Style Guide, you’ll spend a fair amount of time and develop some great ideas. The worst thing I see happen is that teams get busy and don’t take the time to enforce r style and standard. The end result is messy, unclean code that is difficult to maintain and costs more in the long wrong. Failure to follow the Coding Style Guide is technical debt that no team should allow.
There are two ways for your team to check for coding style compliance; during peer code reviews and through lint or static analysis tools. Code reviews are a good time to verify that an automated tool caught everything. My preference for code reviews is to focus on feature and implementation correctness, not style correctness.
Using lint or static analysis tools is the best way to enforce your coding style. Automated tools can also be used to mostly check for MISRA and AUTOSAR compliance as well. There. area lot of options for tools ranging from free, open-source tools to commercial tools. A quick list of tools that I often use can be found below:
I would recommend you try a few of them out and see which one or two work the best for you.
Conclusions
The key takeaway from this blog is that consistency is key to a successful coding style guide. Consistency within a team is achieved by documenting the coding style used, using a lint or static analysis tool to verify the coding standard is being met, and using peer reviews where tools may come up short. The primary purpose of a coding style guide is to allow a code base written by a team of engineers to look like a single developer wrote all the code. A consistent style makes it easier to review code and spot issues rather than having the mind distracted by where brackets are located or the way a variable is named.
A clean coding style will allow a team to decrease bugs, spot potential problems, and reduce time to market. Key questions you should be asking yourself and your team are:
- Do we have a coding style guide?
- Are we using our coding style guide?
- Is our coding style guide enforced automatically by static analysis tools?
- Does our coding style guide follow our industry’s best practices?
References
[1] Autosar Guidelines for C++ 14 in Critical and Safety-Related Systems
