embedded software boot camp

Firmware Code of Ethics

Friday, September 15th, 2006 by Michael Barr

WE THE MEMBERS OF THE EMBEDDED SOFTWARE COMMUNITY, in order to protect our customers (and their customers) from the risks inherent in our products, extend product lifetimes, lower long-term maintenance costs, promote the general welfare of society, and advance the integrity and reputation of our profession, do hereby ordain and establish the following code of ethical conduct.

Check return codes. If a function can return an error code, it will almost certainly return one eventually. How will our software recover if it doesn’t even know an error has occurred? We will, therefore, always check all return codes. When an error is detected, we will take whatever action is required to recover safely.

Document reasoning. We make dozens of design and implementation decisions each week; we forget the reasoning behind others at a similar pace. We will, therefore, document all of our reasoning in the code itself. Furthermore, we will update these comments if our reasoning changes.

Use version control. Even when done carefully and with discipline, making backup copies of source directories, commenting out code that might be needed again, and tracking changes in comments is insufficient. The use of a good configuration management tool is a must. Furthermore, we agree to always perform a diff and provide a good description of the explanation for all changes each time a file is checked in.

Enforce coding standards. No matter how proud we may be of our abilities, we do not “own” the code we produce. Our employers and clients own it; we and others are hired to develop and maintain it. The true owners have the right to enforce a coding standard upon our work. If they do not choose to exercise this right, we will self-enforce a standard in line with generally accepted programming practices.

Run lint regularly. Compilers are more concerned with generating code than the correctness of your syntax. Only a static analysis tool like lint can watch over our shoulders to ensure we’re not straying into dangerous or non-portable programming constructs. We will, therefore, include lint in our development process. If we don’t remove all code with warnings, we will at least understand why each and every warning remains.

Perform code inspections. Automated tools are helpful, but nothing is better than a peer review for finding logic errors. Code inspections have been shown to be many times more efficient than any other single debugging tool. We will always review our code as a group at least once before each release.

Assign one tester to every developer. Programmers make lousy testers, especially when it’s their own code they’re testing. For best results, one independent tester should be hired for every developer. And the testing team must maintain and rerun regression tests regularly, to certify that a new release is at least as good as the previous one.

Measure performance. Of course, there are some kinds of tests that are best performed by the engineers themselves. In real-time systems, we shall directly measure interrupt latency and the time it takes each of our critical subroutines to complete. An oscilloscope and a spare I/O pin are quite handy in this regard.

These best practices are easy things to do, and all are inexpensive to implement. A one or two person design team can as easily follow these rules as a 50-person engineering department. If you aren’t following these rules today, there are no excuses for tomorrow.

Tags: ,

4 Responses to “Firmware Code of Ethics”

  1. Mike Lewis says:

    Check all function parameters, looking for null pointers, other variables that are out of range, sudden and unexpected changes in readouts from hardware, e.g. pitot tubes.

    Make sure your code complies with MISRA C or C++ and the safety checklist in “Targeting Safety-Related Errors during Software Requirements Analysis” (PostScript at
    http://www.cs.iastate.edu/%7Erlutz/publications/sigsoft93.ps
    PDF at
    http://trs-new.jpl.nasa.gov/dspace/bitstream/2014/35179/1/93-0749.pdf)

  2. I would also add “Enforce unit testing” which make sure your functions still work even modified. Unit test execution should be part of a daily/nightly build process reporting errors if found (e.g. via mail). I have found this is quite useful to keep the code in the version control system more stable.

  3. Antonio Leite says:

    My code used to fail most of the time in arrays boundaries. Now I use canary bytes to check it.

  4. […] out my Firmware Code of Ethics, get yourself a static analysis tool, and start following a development […]

Leave a Reply