1.1.1 Readability

Readability in software programming can be defined as the ease with which the software is read and understood. Readability of software can be somewhat objective. Programmers that are “journeyman” and move from one project to another throughout their career tend to have an easier time reading a variety of software code. However, making software more readable helps in reviewing and maintaining it over the course of its life. Simplicity in logic, conditional statements, and the structure of the code all help with readability.

The following is an example of a proper “C” code segment, that isn’t entirely readable:

// Check for stuff to proceed
if((!((Engine_Speed!=0)||(Vehicle_Speed!=0))) || SecureTest!=FALSE ){
 // ABC…
}

With a little better readability, the same conditional can be written as:

// Check for secure testing to be running, or if vehicle is stopped
// along with the engine not running. Then we can execute < ABC >
if (( Secure_Test == TRUE ) || 
 (( Vehicle_Speed == 0 ) && ( Engine_Speed == 0 )))
{
 // ABC…
}

1.1.2 Maintainability

Maintaining the code after it is written is a task that can become extremely difficult. Often the code may not make sense to others that look at it. This can lead to incorrect interpretation, so even though a new feature goes into the code, the existing code around it breaks. If someone besides the author comes into the code to make a change, and if they don’t understand the existing structure, then another “if” condition can be placed at the bottom of the code to avoid making any changes to its top part.

Consider using descriptive comments in the code to capture the “intent” of what is being done. Comments can help clarify its overall purpose later when the code is being updated and the person doing the updates needs a solid reference in terms of the structure of the code. For example, a comment of “Reset timer because if we are here we have received a properly formatted, CRC-checked, ping request message” is much better than “Set timer to 10 seconds.”

1.1.3 Testability

One of the key components for writing good software is writing software with testability in mind. To be “testable” (either for unit testing or debugging) each executable line of code and/or each execution path of the software must have the ability to be tested. Combining executable lines within conditional statements is not a good idea. If an equate or math operation occurs within an “if” evaluation, portions of it will not be testable. It is better to do that operation before the evaluation. This allows a programmer to set up a unit test case or modify memory while stepping through to allow a variety of options in choosing which path to take.

Consider the following code segment:

if ( GetEngineSpeed() > 700 )
{
 // Execute All Speed Governor code
}

For high-level source code debugging, it would not be immediately clear what the engine speed was while debugging. The tester could analyze the register being used for the return value, but it certainly is not readily apparent. Rewriting the code to use a local variable allows the variable to be placed into a watch window or other source analysis window. The code could be rewritten as follows:

current_engine_speed = GetEngineSpeed();
if ( current_engine_speed > 700 )
{
 // Execute All Speed Governor code
}

One argument for this could be program efficiency. This was certainly true years ago when embedded compilers were not very efficient in taking high-level source code and translating it to machine instructions. Today, with compiler optimizers written to look for optimizations via multiple passes through the code, most of these opportunities have been taken care of.

2.2.1 Source Files Written Locally

This directory should contain all the source files that have been written by your development team. Depending on the number of modules being written or the size of the overall code base, consider further subdividing this into more subdirectories and folders. For multiple processor systems, it may make sense to separate by processor (such as “1” and “2”) and have another directory at the same level that contains files common to both.

An additional way to further subdivide a large source files directory is to subdivide it by functionality. Maybe dividing it into major feature groupings, such as “display,” “serial comm,” and “user IO,” would make sense. Indicators of a good project and good directory organization is if software falls into a category easily without a lot of searching around for it or if there are no arguments whether it belongs in one place or another.

2.2.2 Source Files From Company Libraries

This directory should either contain the software or links to the general repository where your company keeps libraries of source files useable in all projects. When doing links, it is important that some sort of control be in place so that new files just don’t show up every time the software is built. Version control needs to be kept tight to ensure no unexpected changes occur between the tested and released baseline. Links to specific versions of files work best. If the files must be physically copied into this directory with no links, it is very important to remember (and have written down) exactly which version was copied. To this end, periodic checking back to the library should be done in addition to checking for newer updates or bug fix releases.

The same approach applies to this directory or folder as mentioned earlier, that is, depending on the number of files being used it may make sense to break it down further into subdirectories or subfolders as well.

2.2.3 Libraries From Third Parties

There may be libraries that are used by third parties as well. There might also be source code—maybe an operating system or network stack that has been provided for you. It is critically important to have these files in a separate directory from the other source files! Programmers need to know that these files probably shouldn’t be changed, but there could be a tie-off that needs to happen with the software provider. If these are mixed in with the general population of source files that are written by the software team, there is a larger risk that they could be changed inadvertently.

Typically, there are files provided by third parties that are supposed to be changed. These may include definitions or links to pieces in the embedded system. For instance, one common entry is defining the number of tasks for an RTOS. Files that are supposed to be changed should either go in their own subdirectory in this group or be pulled over into a folder in the source files that your group is writing. Then privileges like “no modify/no write” could possibly be applied to the folder, to make sure they are not changed.

2.2.4 Libraries From Compiler/Linker Toolsets

There may be restrictions on where the libraries, that the compiler and linker toolsets provide, can be located. Typically, these can just be left alone. All developers need to agree up front which libraries are going to be used. The toolset company may include a full “C stdlib” available for use, or other alternatives like a smaller “micro” library that can be used instead. Trade-offs between the various libraries should be done, like whether the library allows reentrant library use, the functionality that is available, and the size of the library when linked in your embedded system.

There also may be options to remove libraries entirely from use. A common library that we often remove is the floating-point link library. So, library functions like a floating-point multiply (fmul) cannot be linked into the system. If a programmer has a link to this library, it won’t link, and the mistake can be corrected.

2.4.1 Code WhiteSpace

The following are examples of how various software lines can add white space to increase the readability of the code itself. All these examples are operationally equivalent—they produce the same machine code. They are listed in order of the amount of white space they use:

int i;
for(i = 0;i < 20;i ++)
{
 printf(“%02u”,i*2);
}

int i;
for ( i = 0; i < 20; i ++ )
{
 printf( “%02u”, i*2 );
}

int i;
for ( i = 0; i < 20; i ++ )
{
 printf( “%02u”, i * 2 );
}

The examples above concern themselves with the white space that is between the various operators and numbers on a given line of source code. Numerous studies indicate that more white space increases readability in software code. This would support using the third example outlined above. However, if the amount of white space causes the software to wrap to the next line, then too much white space has been used, because wrapping is very unreadable.

2.4.2 Tabs in Source Files

Most syntax standards indicate that tab characters should not be used in source files when writing code. This is because the tab character could be interpreted differently by source editing tools, file viewers, or when it is printed. They are also not readily visible when editing. Source code editors typically provide a way to substitute spaces with the tab character. So, while programming, when the tab key is hit, it automatically replaces the tab with X number of spaces.

This brings about an important point. How many spaces should represent a tab key press or a normal indent in source code? Most editors have a substitution for either “3” or “4” spaces per tab. Either is fine—again, this will be based on some personal preference in addition to how the rest of the code is formatted. In terms of improved alignment, the amount of indent space depends on the spacing that is used for other things, like the “for” loop spacing identified earlier.

2.4.3 Alignment Within Source

How things are aligned in source code makes an impact on readability as well. Take into consideration the following two operationally equivalent sections of code:

int incubator = RED_MAX; /* Setup for Red Zone */
char marker = ‘’; /* Marker code for zone */

int incubator = RED_MAX /* Setup for Red Zone */
char marker = ‘’; /* Marker code for zone */

White space is used on the second example, lining up the variable names, initialization values, and comments on the same column for the code block.

The examples above were quick examples to demonstrate how different code syntax with white space can be used. Consistency and readability are key components to writing good embedded software source code.

3.1.1 Global Variables

Global variables are variables that are visible to any linked component of the system in a single build. They could be declared at the top of a source file but could also be present in header files where the variable is declared in one spot, and then made available as an extern to any other file that includes that header file. There certainly is an entire philosophy associated with global variables—some programmers hate them, and software leads have been known to ban them.

There are differing opinions on the usage of global variables. Programmers can define a correct and “right” way to use them, if they don’t help foster the creation of unorganized (spaghetti) code. There are a couple of guidelines that could be used to allow global variables into your system, as this will typically help increase the performance of the system without using access functions to modify encapsulated local data.

The first is to declare the variable in a header file. Anyone that includes the header file would then have access to the variable, but it also helps make sure that if the global was declared as an unsigned integer all the extern references would match. The header file (ip.h) would look something like this:

#ifdef IP_C
#define EXT
#else
#define EXT extern
#endif

EXT uint16_t IP_Movement_En
EXT uint16_t IP_Direction_Ctrl

#undef EXT

The example above would need each of the source files to declare a definition of their “filename_C” for the variable to be declared. The source file (ip.c) would look like this:

#define IP_C
#include “ip.h”
#undef IP_C
#include … /* Rest of the include files needed by the source file */

By declaring the variable in a header file, the type will be correct, and identifying who is including the header file will also provide a good indication of who might be looking at this variable. Using this type of method could also allow the team to dictate that no global variables are declared in source files—they would be declared in this manner only.

The second recommendation for using global variables is to always prefix the name with the “owner” of the variable itself. In the example above, IP stands for “Input Processing.” So, any variable used with global scope of IP_xxx is a variable declared in the input processing header. This helps by not having a bunch of random names floating around for variables.

The third recommendation that would help make global variable usage easier relates to the second recommendation mentioned above. After a global variable is declared in a header file, the only program that could modify that variable would be an input processing source file, like “ip.c”. Other source files would have “read” access to that variable, but not be allowed to change its value. Of course, the compiler would allow the programmer to change it—but if this was a rule the project team wanted to use it would be easy to find in a code review. Any instance of a variable prefixed with the “ownership” shouldn’t be modified by another program. Consider the source lines below in output processing (op.c):

if ( IP_Movement_En == TRUE )
{
 if (( IP_Direction_Ctrl == IP_FORWARD ) ||
 ( IP_Direction_Ctrl == IP_REVERSE ))

 {
 OP_Display_Movement = TRUE;
 IP_Display_Shown = TRUE; /* Unacceptable… */
 }
 else
 {
 OP_Display_Movement = FALSE;
 }
}

In the example above, we do not want to modify an input processing variable following the third recommendation. This hopefully would be easy to see during a code inspection or review. Instead, consider having input processing figure this out by looking at the variable OP_Display_Movement. If this cannot be done, then a function call from here to an input processing function, having that function change IP_Display_Shown, may work. For debugging purposes, and to try to keep the code organized, having a rule like this in place can make global variables a lot cleaner.

The final recommendation for global variables, in addition to showing “ownership” of the variable by prefixing the source file indicator, is to capitalize each letter in the variable name. This would be a further indication that the variable is a global variable that could be read at multiple places, so changes to meaning, scaling, or size could cause a ripple effect to propagate throughout the system.

3.1.2 File-Scope Variables

File-scope variables are used to share data between multiple functions in a single source file. They are easier to use than global variables, because typically there is a single owner in a particular source file, at least when it is initially written. File-scope variables make it easy to share data between functions, without having to pass them as arguments on the stack.

A key recommendation is to keep the keyword “static” in front of each of the file-scope variables being declared. This keeps them from being used by other files and keeps things local. One issue with this is visibility on the map (or possibly even the debugger) file. For compilers, if a variable is declared in a file without visibility to other files, there isn’t a need to put a reference to it for linking. Sometimes it is nice to be able to see such a variable during source line debugging or peeking at memory while the system is running.

To give such variables visibility during debugging, consider declaring the file-scope variables in the following way in a source file:

STATIC uint32_t IP_time_count;
STATIC uint16_t IP_direction_override;

This “STATIC” definition would then reside in one of the “master” header files in your system. Further discussion of this type of header file (portable.h) is provided in Section 3.2. When compiling the debugger version of your code, the programmer can define a keyword “DEBUG” for those source files—when it is time to release the code the keyword “DEBUG” is not defined. This is particularly useful if there are special setup steps that need to be completed (like turning on a debug function in the microcontroller at initialization). With this type of setup, the following lines would appear in the common header file:

#ifdef DEBUG
#define STATIC
#else
#define STATIC static
#endif

Another recommendation for file-scope variables is the use of capitalized and lowercase characters. Consider prefixing all the file scope variables with the same “filename” or feature set indicator at the front, then making all other letters lowercase. In this way, it will be easy to discern between a global variable and a file-scope variable.

3.1.3 Local Variables

Local variables have the easiest recommendations of all types of variable. The first recommendation is to drop the prefix mentioned in the previous two sections, because it is just a variable within the function. Second, with the use of decent comments, the variable names for local variables really do not need to be overly descriptive. In my opinion, it is alright to have variable names such as n, i, j, etc., when using them to index arrays and loop variables. Even a simple variable like “count” is OK—again if there are comments to let an observer know what the function is trying to do.

The other type of local variable in a function is one with the keyword “static” in front of it. This is used when a variable needs to retain the data through multiple calls of the function, but it is not shared by any of the other functions in a file.

For local variables, consider keeping them as all lowercase. In the case of a “static” variable declared in a function, consider capitalizing the first character. In that way, when looking through the function or maintaining it later, the variable retains its value. The following is an example of how function local variables can look:

static void ip_count_iterations( void )
{
uint16_t i, j, n;
static uint16_t error_count_exec = 0;
uint32_t *reference_ptr;
. . .

Another topic in developing embedded software is the use of conditional compiles in the source code. Conditional compiles allow a compiler to dictate which code is compiled and which code is skipped. There are many books written for software engineering that suggest conditional compiles should not be used in the code.

For hardware-oriented code that is written to work on multiple processors in a system, there may be conditional compiles to specify “Processor A” vs. “Processor B.” For software source code, if > 15% of the source code has conditional compiles in it, consideration should be given to splitting the code, keeping the common code in one file and separating the reason for the conditional compiles between two (or more) files. As the number of conditional compiles increases the readability decreases. Files with minimal conditional compiles are likely easier to maintain than a file that has been branched or separated, but again, as the number of conditional compiles increases past 15% the maintainability drops.

Consider the following source code section for a module written to run on two processors specified as PROCA and PROCB. Depending on which makefile is selected, the compiler defines one of these two values depending on the processor target.

    frame_idle_usec = API_Get_Time();
#ifdef PROCA
/* Only send data when running on processor B */
ICH_Send_Data( ICH_DATA_CHK_SIZE, (uint32_t *)&frame_idle_usec );
#else
#ifdef PROCB
/* Nothing to send with processor B in this situation */
#else
/* Let’s make sure if we ever add a PROCC, that we get error */
DoNotLink();
#endif /* PROCA */
#endif /* PROCB */

There is one additional thing to note with this code. In this example, we do not simply just look for processor A and then do nothing if we are not processor A. There is an else condition, so that if we ever run on a processor besides A or B, a made-up function “DoNotLink()” will be called, which will result in a compiler warning and a linker error (the function doesn’t exist). In this way, if another processor is added in the future it will force the software engineer to look at this code to see if a special case should be added for this new processor. It is simply a defensive technique to catch various conditional compiles that may exist in the source code baseline.

3.3.2 #Define

A commonly used symbolic constant or preprocessor macro in C or C ++ coding is implemented using the    #define.

Symbolic constants allow the programmer to use a naming convention for values. When used as a constant, it can allow better definition as opposed to “magic numbers” that are placed throughout the code. It allows the programmer to create a common set of either frequently used definitions in a single location, or to create more singular instances to help code readability.

Consider the following code segment:

// Check for engine speed above 700 RPM
if ( engine_speed > 5600 )
{

The code segment checks for a value of 5600. But where does this come from? The following is a slightly more readable version of the same code segment:

// Check for engine speed above 700 RPM
if ( engine_speed > (700 * ENG_SPD_SCALE ))
{

This is a little better as it uses a symbolic constant for the fixed-point scaling of engine speed, which is used throughout the software code baseline. There certainly should not be multiple definitions of this value, such as having ENGINE_SPEED_SCALE and ENG_SPD_SCALE both used in the same code baseline. This can lead to confusion or incompatibility if only one of these scalar values is changed. The code segment above also has “700” being used. What if there are other places in the code where this value is used? What is this value? The following code segment is more maintainable and readable:

// Check for speed where we need to transition from low-speed to all-
// speed governor
if ( engine_speed > LSG_TO_ASG_TRANS_RPM )
{

A #define would be placed in a header file for engine speed for visibility to multiple files, or in the header of this source file if it is only used in a file-scope scenario. The #define would appear as:

// Transition from low-speed to all-speed governor in RPM
#define LSG_TO_ASG_TRANS_RPM (UINT16)( 700 * ENG_SPD_SCALE )

This has the additional cast of UINT16 to make sure that the symbolic constant is a fixed-point value so floating-point evaluations are not made in the code. This would be important if the transition speed was defined as 700.5 RPM, or even if a value of 700.0 was used as the transitional speed. Once floating-point values appear in the code, the compiler tends to keep any comparisons or evaluation using floating-point operations.

Preprocessor macros allow the programmer to develop commonly used formulas used throughout the code and define them in a single location. Consider the following code segment:

Area1 = 3.14159 * radius1 * radius1;
Area2 = 3.14159 * (diameter2 / 2) * (diameter2 / 2);

The code listed above can be improved by creating a preprocessor macro that calculates the circular area as opposed to listing it in the code. Another improvement would be to use a symbolic constant for PI so that the code can use the same value throughout. That way if additional decimal places are used, it can be changed in one location. The following could be defined at the top of the source file, or in a common header file:

#define PI 3.14159
#define AREA_OF_CIRCLE(x) PI*(x)*(x)

The code could then use this preprocessor macro as follows:

Area1 = AREA_OF_CIRCLE(radius1);
Area2 = AREA_OF_CIRCLE(diameter2 / 2);

The code segments shown above could be used for a higher end microcontroller that has floating-point hardware or for a processor where floating-point libraries are acceptable. Another implementation could be in fixed-point, where tables would approximate PI values so that native fixed-point code could speed up processing times.