Explaining variables

I recently came across an excellent book: The Art of Readable Code by Dustin Boswell and Trevor Foucher. As soon as I heard about the book, I knew that it would interest me and ordered a copy without delay. For years, I have pushed the message that the #1 priority, when writing code, is readability; the authors and I are on the same wavelength. I am likely to be referring to this book again in this blog, as, on initial reading, although many things are already clear and familiar to me, I still have more to learn and to share …

A common argument for writing complex, hard-to-read code is “efficiency”. Although this is an important matter for many embedded designs, where resources are limited, modern development tools really help to avoid unnecessary obfuscation. Let’s look at an example:

Imagine their is a device, with a control register located at address 0x80000004 and bit 2 indicates that the device has an error. In our software, we reach a point where we wish to execute some code if the device is showing an error and we might do that thus:

if ((*((unsigned *)0x80000004)) & 0x4) != 0)
   ...

This is far from readable and can be improved in obvious ways:

#define MYDEVICE (*((unsigned *)0x80000004))

if ((MYDEVICE & 0x4) != 0) // test error bit
   ...

A further improvement would be to use an intermediate variable to hold the result of the test – an “explaining variable”:

#define MYDEVICE (*((unsigned *)0x80000004))

unsigned DeviceError;

DeviceError = MYDEVICE & 0x4;   // test error bit

if (DeviceError != 0)
   ...

Is that clearer? I believe that it is. However, I can hear a “non-believer” complaining: “That intermediate variable is an unnecessary overhead!” This would be true, except that a modern, optimizing compiler would certainly eliminate the variable if it were used just once. If It were to be used again, the variable would probably be instantiated, but the test would only be performed once, so the overhead is well worthwhile. In any case, it may be allocated to a machine register, which minimizes the impact.