Rules
The following C coding rules relate to certain keywords of the language that should be favored to reduce bugs:
Rule 1.8.a.) The static
keyword shall be used to declare all functions and variables that do not need to be visible outside of the module in which they are declared.
Rule 1.8.b.) The const
keyword shall be used whenever appropriate. Examples include:
- To declare variables that should not be changed after initialization,
- To define call-by-reference function parameters that should not be modified (e.g.,
char const * param
), - To define fields in structs and unions that should not be modified (e.g., in a
struct
overlay for memory-mapped I/O peripheral registers), and - As a strongly typed alternative to
#define
for numerical constants.
Rule 1.8.c.) The volatile
keyword shall be used whenever appropriate. Examples include:
- To declare a global variable accessible (by current use or scope) by any interrupt service routine,
- To declare a global variable accessible (by current use or scope) by two or more tasks,
- To declare a pointer to a memory-mapped I/O peripheral register set (e.g.,
timer_t volatile * const p_timer
), and - To declare a delay loop counter.
Reasoning
C’s static
keyword has several meanings. At the module-level, global variables and functions declared static
are protected from external use. Heavy-handed use of static
in this way thus decreases coupling between modules.
The const
and volatile
keywords are even more important. The upside of using const
as much as possible is compiler-enforced protection from unintended writes to data that should be read-only.
Proper use of volatile
eliminates a whole class of difficult-to-detect bugs by preventing compiler optimizations that would eliminate requested reads or writes to variables or registers. (Note: Anecdotal evidence suggests that programmers unfamiliar with the volatile keyword think their compiler’s optimization feature is more broken than helpful and disable optimization. We believe that the vast majority of embedded systems contain bugs waiting to happen due to missing volatile keywords. Such bugs typically manifest themselves as “glitches” or only after changes are made to a “proven” code base.)
Exceptions
None.
Enforcement
Appropriate use of these important keywords shall be enforced during code reviews.
Comments:
How to Use C's volatile Keyword
The proper use of C's
volatile
keyword is poorly understood by many programmers. This is not surprising, as most C texts dismiss it in a sentence or two. If you need to learn how to usevolatile
properly, read:How to Use C's volatile Keyword