Tag - documentation

Entries feed - Comments feed

Last entries

Tue 17 Dec 2013

Book review: Better Embedded System Software

better_embedded_system_software_cover.gif Better Embedded System Software is a very good book if you write software, and not only embedded software!

I discover this book when following the Toyota Unintended Acceleration case where Philip Koopman, the author of this book, was a plaintiff's expert. Philip Koopman is an Associate Professor at the Carnegie Mellon University.

Why is this book so good? Because it explains in daily words what should be the ideal software development process. And not only it details the ideal process, but it gives concrete, down to earth advices on how to improve your current process and software development habits.

The book is divided into 30 small chapters, following the order of the usual V cycle (overall process, requirements and architecture, design, implementation, verification and validation, critical system properties). The chapters are very short, about 10 pages, and relatively independent. This one of the great point of the book: it is easy to read a chapter, there is not need to allocate a long time slot for it. You can pick the chapter that is most interesting to you. And as the chapters are right to the point, you immediately get useful advices and you can immediately start to apply them on your own development.

The other great quality of this book is that the author has a strong background in embedded software development. Therefore the advices are realistic and graduated. The author knows that you are going to find barriers and limitations in your work environment and he helps against them. For example, there are two chapters on producing some documentation but not too much. Even if you cannot apply the whole set of advices, you nonetheless get some ideas on own to improve your current software and what could be done in later steps.

I am not an expert on all the topics presented in this book (that's why I bought it!) but for the domains I knew (e.g. concurrent programming), the advices seem balanced and appropriate.

Of course, 10 pages for a chapter is very short and some subjects are so wide that they would deserve a book on their own (e.g. safety and security). In that case, Koopman's book give useful pointers to continue your reading and the summary he gives is an excellent introduction to the topic.

As I said many times, we are currently making very bad software and we should improve this situation. Better Embedded System Software is the one the very few books that you should keep close to your table and consult on a regular basis.

If you cannot afford the book, some quite detailed slides on Avoiding the 43 Top software risks have been made available by Philip Koopman.

Wed 06 Oct 2010

  • David Mentré
  • 2

What is it important to document?

When you write some code, what should be documented, either through the comments, a separate documentation or by using literate programming?

I personally see three important points:

  • The why: why the software is designed that way, why using this algorithm instead of another, the rationale behind a specific design, etc.
  • The global overview: giving all the clues that will help a new reader to quickly grasp your code and find his/her way through it. Some people would call it the architecture;
  • The non-obvious: make explicit things that are in your code but might only be understood after a deep fall into the code (e.g. the graph of a state machine which is encoded in a complicated way for improved efficiency, subtle race-conditions to avoid when using some locks, ...).

I am probably the first to not follow this advice. But I should! ;-)

What is your opinion?