Beautify firmware to ease development
Well-developed firmware can be a beautiful thing. Unfortunately, most of the code I review is not only not beautiful it's not even pretty. Firmware that is clean, aligned, and easy to read is pretty, but more importantly it is also generally more understandable than code that isn’t. That boost in understandability makes the code easier to debug and maintain. Here are a few thoughts on how to make sure your firmware is prettier and more readable.
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. Yet even though using a style guide is an obvious thing to do, I see a lot of developers that either don’t have a style guide 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 allows a developer to easily adapt them to their own style and purpose. Developers need to ensure that their style guide is enforced through peer reviews or the use of automated tools.
Thought #2 – Set consistent 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 these editors handle spaces and tabs is just different enough to destroy the spacing and alignment of code when code segments developed under different editors are brought together. 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.
Traditionally an editor's tab settings are set to eight characters, but there is no guarantee that tis always holds true. A few of the editors that I use, for instance, set tab spacing to four characters 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.
Thought #3 – Use tab to space conversion
Let’s be honest, developers shouldn’t be using tab to align their code anyway. 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?
Fortunately, 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, freeing its alignment from editor settings. The trick, of course, is to first make sure that the appropriate tab setting is configured and then 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 can still get stuck with nasty looking code. The reason? Open source code. Many developers prefer or get forced to use open source software that on a good day usually looks like a rat's nest or a plate of spaghetti. 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 aligned and readable. 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, though. A developer should already 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.
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. It's worth the time and effort, then, to create code that is pretty.
What others thoughts and tips do you have on how to make sure that firmware looks good?
Jacob Beningo is principal consultant at Beningo Engineering, an embedded software consulting company. Jacob has experience developing, reviewing and critiquing drivers, frameworks and application code for companies requiring robust and scalable firmware. Jacob is actively involved in improving the general understanding of embedded software development through workshops, webinars and blogging. Feel free to contact him at firstname.lastname@example.org, at his website www.beningo.com, and sign-up for his monthly Embedded Bytes Newsletter here.