The Ten Commandments for C Programmers

News from Embedded Systems Conference 2009, in San Jose: “Accomplished for the first time in a commercially available phone, Chicago-based Open Kernel Labs’s mobile virtualisation solution enabled Linux and an RTOS to run side by side on a single ARM processor.”

The firm produces the ‘virtualisation’ software: code which controls access to hardware resources, allowing both the RTOS and Linux to run separately as though there were the only operating system on the processor. Such software is also known as a hypervisor.

Read the full article: OKL hypervisor runs Linux and RTOS on Motorola’s QA4

Many years ago Henry Spencer wrote down what he considered to be ten of the most fundamental rules all C programmers should follow. Reading them now they seem almost funny (anyone still program for a VAX?). But for an embedded engineer they still ring true.

The Ten Commandments for C Programmers

  1. Thou shalt run lint frequently and study its pronouncements with care, for verily its perception and judgement oft exceed thine.
  2. Thou shalt not follow the NULL pointer, for chaos and madness await thee at its end.
  3. Thou shalt cast all function arguments to the expected type if they are not of that type already, even when thou art convinced that this is unnecessary, lest they take cruel vengeance upon thee when thou least expect it.
  4. If thy header files fail to declare the return types of thy library functions, thou shalt declare them thyself with the most meticulous care, lest grievous harm befall thy program.
  5. Thou shalt check the array bounds of all strings (indeed, all arrays), for surely where thou typest “foo” someone someday shall type “supercalifragilisticexpialidocious”.
  6. If a function be advertised to return an error code in the event of difficulties, thou shalt check for that code, yea, even though the checks triple the size of thy code and produce aches in thy typing fingers, for if thou thinkest “it cannot happen to me”, the gods shall surely punish thee for thy arrogance.
  7. Thou shalt study thy libraries and strive not to re-invent them without cause, that thy code may be short and readable and thy days pleasant and productive.
  8. Thou shalt make thy program’s purpose and structure clear to thy fellow man by using the One True Brace Style, even if thou likest it not, for thy creativity is better used in solving problems than in creating beautiful new impediments to understanding.
  9. Thy external identifiers shall be unique in the first six characters, though this harsh discipline be irksome and the years of its necessity stretch before thee seemingly without end, lest thou tear thy hair out and go mad on that fateful day when thou desirest to make thy program run on an old system.
  10. Thou shalt foreswear, renounce, and abjure the vile heresy which claimeth that “All the world’s a VAX”, and have no commerce with the benighted heathens who cling to this barbarous belief, that the days of thy program may be long even though the days of thy current machine be short

As an embedded engineer I still believe these are good rules to follow.

I don’t use lint much any more, but I do ensure that all warnings are enabled from my compiler and I read them all. Why? Because I know I make typos. I know I make mistakes from time to time and I really appreciate the help the compiler can give me. But the compiler is not perfect so I also recommend code reviews by other engineers. A fresh pair of eyes can often spot something neither you nor the compiler noticed.

Do you check all your array indexes? Make sure strings will fit into allocated buffers? These are sources not only of potentially annoying bugs but also security vulnerabilities.

Do you test the return codes from all functions that may return them? Yes? Good, but do you test the branches of code that should handle those errors when they occur? It is never as easy as you think it will be. When you are writing a test harness (you do write those don’t you?) you should also be using a code coverage tool to make sure you tested what you thought you did.

Make good use of the libraries already available. Not only are there already many excellent, high quality libraries available for C but for other languages too. If you are a C++ programmer then don’t forget Boost or Qt (now available under an LGPL license) too.

Whilst the world is not a VAX any more, neither is it an x86. Consider that your code may run on a PowerPC, ARM, MIPS or any of the many other architectures supported by Linux. Some processors are big endian, others little. Some 32-bit and others 64. Most are single core but increasingly they are multi-core.

Ignore these commandments at your peril.

Related posts

4 Comments

  1. Russ Klein
    April 23, 2009 18:29

    It seems odd to me that one would take a real time operating system and run it on a hypervisor. Yes, an interesting academic exercise – but doesn’t this throw out everything that RTOS delivers in terms of RT (real time)? In this configuration, how does one balance the priorities of threads, tasks, or processes across the multiple operating systems? How does one ensure realtime responses? How does one prevent deadlocks and resolve contention between resources that are shared between OSes run in the hypervisor?
    VxWorks and other embedded RTOSes have a rich set of facilities to support achieving the real time compute requirements of an embedded system. The use of a hypervisor in a real time system negates all that capability and forces us to solve these problems all over again in a new environment.

  2. Richard Danter - Wind River
    April 06, 2009 09:08

    Yes, the 9th rule refers to some really old compilers which used only the first six characters of a symbols name to identify it. So in your example it would treat all your symbols as being called “Pumpki”.
    Fortunately I don’t think there are any compilers with this limitation any more. If you are unfortunate enough to have one then I would recommend you upgrade!

  3. April 05, 2009 21:39

    Test harnesses, eh. I reckon that may sort the men from the boys. I wonder how many programmers automate testing of their code? (function, by function)
    In another existence, as a relatively junior programmer, I remember being very impressed by a senior testing a program of mine via a test rig / code harness he put together specially. Sure enough, it highlighted a hidden bug whereby a particular data sequence would not be successfully written. The chance of finding that sequence by ad-hoc testing was virtually nill….
    Actually, I would like to throw that open to fellow readers of this blog – What is the most difficult application you have worked on? (in terms of development constraints or testing difficulties). The project for me, described above, was a block-box protocol converter, emulating one type of PLC as another. The only possible visible outputs were four LEDs… not easy to debug!

  4. Rich D
    April 04, 2009 21:50

    The 9th commandment is a new one on me. I was taught to write all library functions in a kind of inverted-pyramid style with the verb at the end: To get a byte from a serial port of the Pumpkin board, I should name my function PumpkinSerialByteGet, so that someone new to the code knows exactly what file to look in if they think there’s a problem with byte reading. It also makes it easy to find all other functions related to the Pumpkin serial driver by just searching for “PumpkinSerial”.