Developing firmware can be a beautiful thing but most of the code I review is not very pretty. Firmware that is highly readable can be easier to maintain and debug. Here are a few thoughts on how to make sure that firmware is readable even under the worst of conditions.

Thought #1 – Follow a style guide

Following a style guide is probably one of the most obvious ways in which to get code that is clean and human readable. The strange thing about the obviousness of using a style guide is that I see a lot of developers that either don’t have one or completely ignore the one that they have. A style guide has the advantage of defining how every developer should organize the aesthetics of their code. The results of being disciplined and using a style guide properly is a uniform code base that looks identical.

There are many good examples of style guides available on the web. Most of the examples are provided in a word format that allow a developer to easily adapt to their own style and purpose. Developers need to ensure that the style guide is enforced through peer reviews or the use of automated tools.

Thought #2 – Set tab spacing

If one were to place ten developers in a room and ask them what their favorite text editor is, the result would most likely be ten different answers. The answers would undoubtedly range include Eclipse, SlickEdit, Sublime Text, NotePad++, VIM, Nano and so forth. Every developer has their own preference and as one might expect, the way that spaces and tabs are handled in these editors is just different enough to destroy the spacing and alignment of code.

Traditionally the tab settings are set to eight characters but there is no guarantee. A few of the editors that I use set it to four by default. A good style guide should tell developers what settings to use in their IDE so that once code is written in one editor, the code can easily be opened in another without the loss of spaces and code alignment. There are few things more annoying than opening a file only to find that a once nicely aligned configuration table is now only partially aligned.

Thought #3 – Tab to space conversion

Let’s be honest, developers shouldn’t be using tab to align their code. A developer should be using the spacebar but who really wants to press the spacebar three or four or more times when a single key press will do? Many text editors have a hidden feature that will convert any tabs in a file into equivalent spaces! Tab to space conversion allows a developer to bang out code at a fast rate and then convert the tabs before committing the code. The trick of course is to first make sure that the appropriate tab setting is configured and to be disciplined enough to run the converter.

Thought #4 – Use a code beautifier

Even the most disciplined developers who follow the style guide and set their tab spacing’s can get stuck with nasty looking code. Many developers prefer or get forced to use open source software that usually looks like a rats’ nest or a plate of spaghetti on a good day. Have you ever taken a look at the example code provided by any sensor or chip manufacturers? Let’s just say the word beautiful normally doesn’t come to mind. Thankfully developers can take advantage of code beautifiers.

A code beautifier is a simple tool that scans through a text file and formats the file based on the input formatting settings. Code that is poorly aligned and difficult to read can magically be converted to code that is readable and aligned. A simple google search for code beautifiers reveals a large number of free and online code beautifiers. There are also a number of commercial code beautifiers that are available for less than $100.

A code beautifier really shouldn’t be used to clean-up code that a developer is writing. A developer should be following their own style guide and developing software in a disciplined manner. The code beautifier tool should only be used to clean-up that vendor or open source code that doesn’t meet the style guide.

Conclusions

Firmware that is clean, aligned and easy to read is generally more maintainable and understandable than code that isn’t. Due to the ease at which the code can be understood, developers can save development time and perhaps most importantly reduce the likelihood of accidentally injecting a bug into their software.

What other thoughts and tips do you have on how to make sure that firmware looks good?