Barr Group FacebookBarr Group TwitterBarr Group LinkedInBarr Group Vimeo

Rules

The following C coding rules relate to the naming of variables in embedded software:

Rule 7.1.a.) No variable shall have a name that is a keyword of C, C++, or any other well-known extension of the C programming language, including specifically K&R C and C99. Restricted names include interrupt, inline, restrict, class, true, false, public, private, friend, and protected.

Rule 7.1.b.) No variable shall have a name that overlaps with a variable name from the C Standard Library (e.g., errno).

Rule 7.1.c.) No variable shall have a name that begins with an underscore.

Rule 7.1.d.) No variable name shall be longer than 31 characters.

Rule 7.1.e.) No variable name shall be shorter than 3 characters, including loop counters. (Note: This is because you can’t do a meaningful global search for “i”.)

Rule 7.1.f.) No variable name shall contain any uppercase letters.

Rule 7.1.g.) No variable name shall contain any numeric value that is called out elsewhere, such as the number of elements in an array or the number of bits in the underlying type.

Rule 7.1.h.) Underscores shall be used to separate words in variable names.

Rule 7.1.i.) Each variable’s name shall be descriptive of its purpose.

Rule 7.1.j.) The names of all global variables shall begin with the letter g. For example, g_zero_offset.

Rule 7.1.k.) The names of all pointer variables shall include the letter p. For example, p_led_reg.

Rule 7.1.l.) The names of all pointer-to-pointer variables shall include the letters pp. For example, gpp_vector_table.

Rule 7.1.m.) The names of all integer variables containing “effectively Boolean” information (i.e., 0 vs. non-zero) shall begin with the letter b and be phrased as the question they answer. For example, b_done_yet or gb_is_buffer_full. (Note: It is unsafe, in C, to define constants such as TRUE and FALSE where TRUE is equal to 1. However, it is safe to compare “effectively Boolean” integer values against 0. For example, the test if (!gb_buffer_is_full) is safe and consistent with Rule 13.2 (advisory) of [MISRA04]. Note too that [C99] adds <stdbool.h>, which defines a bool type and C++-like constants true and false.)

Reasoning

The base rules are adopted to maximize code portability across compilers. Many C compilers recognize differences only in the first 31 characters in a variable’s name and reserve names beginning with an underscore for internal names. The other rules are meant to highlight risks and ensure consistent proper use of variables.

Exceptions

None.

Enforcement

These variable-naming rules shall be enforced during code reviews.

Comments:

I have wanted to like Hungarian notation naming conventions, but never found their value to outweigh costs, such as keeping variable names in sync with their types.

Having spent a great deal of time lately writing and reviewing C code that follows the Barr Group standard, I endeavored to follow these naming rules very closely. And I have followed these Hungarian rules, despite my general dislike.

However, having to prepend a b as well as come up with a name to follow the "question they answer" rule in 7.1.m has come to feel to me to seem overbearing with very little practical value.

First let me say thank you for choosing to follow our coding standard. And also for taking the time to share your concerns about this rule.

I also generally disfavor Hungarian notation, having done enough Windows app developing work to have nightmares about happening upon cryptic variable names like a_crszkvc30LastNameCol.

However, I was convinced by members of our engineering team that there was value in following the few minor uses of Hungarian that ended up in our standard, including:

  • g_: because I've seen how it really helps reveal the use of singleton objects that need to be protected from simultaneous access;
  • p_: because I found pointers and pointers-to-pointers much easier to correctly use when when writing the code when this naming convention is applied; and
  • b_: because it allows me to test a Boolean's truth (vs. 0 or non-0) without an explicit ==, which eliminates another common bug.

Our suggestion that the Boolean-type variables be named according to the "question they answer" is meant to aid code readability and thereby maintainability. For example, even without comments the following code should be easily understood by all:

if (b_weapon_is_armed)
{
    ...
}
else
{
    ...
}

If you don't like following that part of the rule, I suggest looking at the instructions in the standard's Deviation Procedure.

Following up to smccord's comment (which I agree with), why not simply dictate that C99's built-in bool type be used for boolean variables?  There is a standard header file <stdbool.h> that makes this type available.  Since best practices recommend using other types such as uint8_t and int32_t, why not bool as well?  Then IMO the whole naming quandary goes away.

What’s happening and how it’s done. Get in the know.

Sign up for our newsletter today!

Receive free how-to articles, industry news, and the latest info on Barr Group webinars and training courses via email. 

To prevent automated spam submissions leave this field empty.