Pebble Bay Pebble Bay
  • Home
  • About Us
  • Services
    • Embedded software services
    • Embedded software porting
    • Embedded system development
    • Embedded systems optimisation
  • Solutions
    • Embedded software for telecommunications
    • Embedded software for military and aerospace
    • Embedded software for industrial automation
  • Resources
    • Blog
    • Case studies
    • News
  • Contact Pebble Bay
Pebble Bay Pebble Bay
  • Home
  • About Us
  • Services
    • Embedded software services
    • Embedded software porting
    • Embedded system development
    • Embedded systems optimisation
  • Solutions
    • Embedded software for telecommunications
    • Embedded software for military and aerospace
    • Embedded software for industrial automation
  • Resources
    • Blog
    • Case studies
    • News
  • Contact Pebble Bay
Feb 20
Embedded code

Why is so much Embedded Code Unreadable?

  • February 20, 2015
  • Ian Willats
  • 2 Comments
  • Blog

The idea of readable code – that it should be written to make it as easy as possible for future readers to understand – is not new. Brian Kernighan and PJ Plauger’s book, The Elements of Programming Style, was first published in 1974, around the same time as the embedded software industry was taking off. Since then there have been many well-known books that cover similar ground (listed below).

The importance of readability is not just about aesthetics and beautiful code – although that plays a part – but it relates directly to the overall lifecycle cost of software. Code that is hard to read is more likely to have undiscovered bugs, and is inevitably harder to maintain than readable code. This is surely as much of an important factor for embedded software as it is in other fields.

You’d think, then, that developers building embedded systems 40 years later would be applying these principles as a matter of course. But at Pebble Bay, where we often work with source code from other companies, we find this is rarely the case: embedded software source code is often very hard to read – sometimes shockingly so. There are exceptions, of course, but in most cases, code that we inherit from other companies falls a long way short of the standards for readability that we set ourselves.

This raises some obvious questions. First, is this unique to embedded software? That’s hard to answer without knowing about non-embedded software development, but for us it’s a moot point anyway.  Secondly, why is there apparently so little regard for readability of embedded software?

Advice and guidance on readable code

It can’t be for lack of guidance. Apart from the excellent (though now dated) Kernighan and Plauger book, there’s a wealth of advice on how to write readable code. Some of our favourites at Pebble Bay are:

  • Code Complete, by Steve McConnell (Microsoft Press)
  • The Practice of Programming, by Brian Kernighan and Rob Pike (Addison-Wesley)
  • The Pragmatic Programmer, by Andrew Hunt and David Thomas (Addison-Wesley)
  • The Art of Readable Code, by Dustin Boswell and Trevor Foucher (O’Reilly)

These books present many principles and practical techniques to improve the readability of code. The techniques apply from the micro level – within single lines of code – to the macro level – organisation of projects. Furthermore, there’s a lot of consistency and agreement between different writers. So the truth is out there, at least in traditional published book form.

While a web search for “readable code” returns many interesting blog posts and articles, “readable embedded code” brings up more or less nothing directly related to the topic. I find that interesting, but also rather disturbing. Of course, you can apply the same general principles to embedded software development, but does this mean no-one developing embedded software takes readability seriously enough to talk about it?

Perhaps it’s not quite that bad. One of my favourite embedded software blogs is Nigel Jones’ Stack Overflow (http://embeddedgurus.com/stack-overflow) where readability and maintainability are recurring themes. For example, his June 2012 post The Crap Code Conundrum explores similar ground to this article.

Possible reasons for poor readability of code

I can think of several reasons why embedded software might be unreadable:

  • Not enough experience or knowledge of how to make code readable
  • Lack of pride and/or perceived value in producing readable code
  • Not enough incentive or motivation to make the code readable
  • Time pressure precluding (perceived) effort needed to make the code readable
  • Code prematurely ‘optimised’ at source code level resulting in poor readability
  • No process to ensure or improve readability

There are a couple of threads here. One is a personal quest for self-improvement and a pride in writing high-quality, readable code. That depends on developing the maturity to avoid overly-dense, complicated or ‘clever’ code either for its own sake or in a misguided attempt to improve some vague notion of ‘efficiency’. Different people may have that self-awareness, self-discipline and drive for improvement to different degrees. Interestingly, Nigel Jones suggests that low awareness of the need for readability and maintainbility is probably the most likely cause for the poor quality of a lot of embedded code.

But the second thread is that an organisation that depends on embedded code must make readability a stated, explicit goal – and maybe even enforce quantitative measures of readability where possible.  This implies the need for a process, to reduce the dependency on individual attitudes and capabilities.  Without this, organisations can’t consistently develop readable, maintainable code and will therefore spend more time and money than they need to over the complete life of their software.

I would argue that this focus on readability is an essential part of a software engineering process, and in fact, should not add much extra effort within that context. Just to pick a simple example: you’re almost certainly going to review the code to detect defects, so the same review is an ideal opportunity to ensure and improve readability.

What is needed to improve readability of code?

At Pebble Bay we’ve determined that three things are needed to consistently develop readable code:

  • a commitment that code readability is required and will not be compromised;
  • a set of standards, principles and guidelines to explain what ‘readable code’ means and how to achieve it; and
  • a consistently-applied review process to ensure that code meets or exceeds the agreed standards.

After all, this is hardly a radical conclusion – you could replace ‘readability’ with ‘low rate of defects’ and exactly the same approach would apply. So is there something missing? What other reasons are there for the low standard of readability in embedded code, and what techniques do you use to improve it?  What characteristics best define readable code for you?

  • Facebook
  • Twitter
  • Tumblr
  • Pinterest
  • Google+
  • LinkedIn
  • E-Mail

About The Author

Ian Willats is the Managing Director and Co-founder of Pebble Bay. Ian has more than twenty years experience in developing real-time and embedded software, including consultancy and project management.

2 Comments

  1. vic plichota
    February 24, 2016 at 1:16 am · Reply

    Hi Ian; besides the oft-cited “delivery schedule” problem (which of course actually means an *unrealistic* delivery schedule), I suspect that very often the programmer is flying solo; there *aren’t* any teammates for code reviews. This has certainly happened to me, and I must admit that I have written some very sloppy atrocious code when only I will ever see it; I’m much more careful, when I know that other people — people who’s opinions I value and respect — will be looking at it.

    This is a bad habit that I continue striving to eliminate, and now try to ensure that *all* my code is exemplary, with nothing to apologize for… Which leads to another problem that I’ve encountered: derailment.

    The code has *functionally* passed through the shakedown iterations, and has graduated to commitment in the production release. I’m now going to tidy it up and make it nicely readable (if not utterly beautiful), really, I am. But then comes an “urgent priority” to work on a different module, then another, and another…

    The road to hell is paved with good intentions. :-/

    cheers, – vic

    • Ian Willats
      February 24, 2016 at 8:53 am · Reply

      Hello Vic – thanks for your comment. I recognise those effects too; personally, the way I’ve learned to avoid them is to get in the habit of writing the code “nicely” at all stages of a project. If you like to think of it that way, I am my own code reviewer. Even when prototyping, the time spent in apparently cosmetic detail is usually repaid later in the project. That way there is no large, looming clean-up task that — as you say — tends to never get done. Sure, when my colleagues review the code they pick up defects that need to be fixed, but at least there is (usually) a manageable number of them.

Leave a reply Cancel reply

Your email address will not be published. Required fields are marked *

Sign up for our monthly e-newsletter!

Given email address is already subscribed, thank you!
Oops. Something went wrong. Please try again later.
Please provide a valid email address.
Thank you, your sign-up request was successful! Please check your e-mail inbox.
Please complete the CAPTCHA.
Please fill in the required fields.

Recent Posts

  • Why become an embedded software developer?
  • Embedded design projects: Challenging what the client wants
  • Security Issues with the IoT
  • Why is so much Embedded Code Unreadable?
  • 7 Uses for a Serial Port in an Embedded System

Recent Comments

  • Mark Hermeling on Why become an embedded software developer?
  • poojashree on Security Issues with the IoT
  • linuxnoob on A guide to using Direct Memory Access in Embedded Systems – Part Two
  • Kzzircuit on Why become an embedded software developer?
  • Sanjay on VxWorks development – when hardware doesn’t support Ethernet

Archives

  • January 2017
  • November 2016
  • June 2016
  • February 2015
  • January 2015
  • December 2014
  • November 2014
  • October 2014
  • September 2014
  • August 2014
  • July 2014
  • June 2014
  • February 2014
  • November 2013
  • September 2013
  • August 2013
  • April 2013
  • January 2013
  • December 2012
  • October 2012
  • May 2012
  • November 2011
  • August 2011
  • May 2011
  • September 2010
  • August 2010
  • April 2010
  • January 2010

Recent posts

  • Why become an embedded software developer?
  • Embedded design projects: Challenging what the client wants
  • Security Issues with the IoT
  • Why is so much Embedded Code Unreadable?
  • 7 Uses for a Serial Port in an Embedded System

Contact

168 Parade, Leamington Spa, CV32 4AE Phone: +44 (0) 1926 421 700 E-Mail: info@pebblebay.com Web: www.pebblebay.com

Newsletter

Given email address is already subscribed, thank you!
Oops. Something went wrong. Please try again later.
Please provide a valid email address.
Thank you, your sign-up request was successful! Please check your e-mail inbox.
Please complete the CAPTCHA.
Please fill in the required fields.

How we use cookies, Legal notices, Accessibility

Digital Marketing by Rokman Laing