C programming language coding guidelines

Copyright © 1993,1998 Eric Laroche
All rights reserved

Contents

The paper shows the abstractions and considerations that lead to recommendations in C programming. It is the author's opinion that all the coding recommendations can be deduced from general coding aims.

Aim of coding

• error free design (which is sometimes only proven in the implementation phase)
• error free algorithms
• error free code architecture (what is to be known as bugfree¹)

Note that software defects can be a security problem².

Then, software engineering aims are

• maintainability (ease of expanding or correcting code)
• reusability

The importance³ of the software engineering issues mainly depends on the overall size of a project. If you intend to expand the project or to convert parts of it into a (reusable) software library, software engineering issues should be considered from start on.

We can say that the smaller the project, the more likely it is manageable without considering software engineering issues. However, if your design and coding experience allows, I recommend not to neglect software engineering issues even with the smallest projects, since

• a project may (later) expand to a much larger size
• projects code fragments may become part of a software library

• less defective
• more robust (against changes in code architecture)
• more readable⁴ (for easier maintenance)

Design issues are not so much covered in this paper, since they are often independent of the programming language.

This paper won't compare the C programming language to other programming languages. Some aspects, like efficiency and economy of a programming language depend heavily on a programming environment's implementation⁶. Other aspects, like reliability (e.g. through pre- and postconditions) can be seen in the C language as part of the design rather than coding.

However, a few footnotes are included about better approaches of the C++ language in (not object orientated) language details.

C language definition

There is an older standard K&R1 (Kernighan/Ritchie, 1st Edition 1978), also known as pre-ANSI-C.

Use the newer standard if possible. It does rigid type checking (and implicit casting if necessary) on function arguments (provided that function prototypes and appropriate header files are used).

Tools to convert from K&R1 to K&R2 or to add function prototypes are available (e.g. protoize).

Internationalization

You should limit yourself to the ASCII character set in C source files. The printable ASCII characters are represented by the bytes hexadecimal 20 to 7e.

Non-ASCII characters (e.g. ISO-Latin above hexadecimal 7f) are syntactically incorrect when used for identifier names (even if some compilers may accept such identifiers).

Comments, strings and character literals should not contain non-ASCII characters.

Non-ASCII characters and control characters (hexadecimal 0 to 1f, with the exception of newline, carriage return, tabulator and formfeed) may confuse editors or may even lead to unexpected results on some compilers (e.g. ^Z misinterpreted as end-of-file, most significant bit stripped on non-ASCII characters, etc.). There is no means of notation of the encoding type of a source file (unlike with mail messages).

C offers nice ASCII-notations for non-ASCII characters, e.g. '\xe8'.

Coding language

To let the sources be globally readable, the lingua franca of computer science, english, should exclusively be used. As with other parts of the C coding guidelines: the smaller the scope context, the less strict the rule.

Customizing your program's user interface to a local language (i.e. internationalization in the stricter sense) can be done with locales and e.g. the gettext() family of functions. These functions let you use compiled text databases for the different ISO language codes, while leaving your C sources still readable, i.e. (english) strings are still present in the code.

Note that internationalization covers also local formats for things like dates and money.

Identifier names

There are of course many styles of choosing identifier names. One important rule is to be consequent about naming.

The smaller the scope of a name, the less important a good choice of the name is. E.g. it is less important to chose a speaking and somewhat systematic name for a small scope index variable⁸ than it is for an exported library function.

Using capable development environments (the ones that let you jump to definition and declaration of a function) makes it less important to express type and package membership in a function name.

The aspect of which natural language to use for names has already been covered.

Name styles

• use of underscore characters⁹ (e.g. get_name)
• use of upper case initials (e.g. GetName)
• use of natural language context (e.g. getname)

Some software packages use a kind of type prefix (e.g. uppercase initial for functions and lowercase type indicating initials for variables). E.g.: sz (zero terminated string), n/i (integer), p (pointer), psz (zero terminated string pointer), f/b (flag, boolean), c (character), fp (file pointer), pfn (function pointer), h (handle), w (word, unsigned int), fd (file descriptor).

Package prefixes (e.g. t_ in the TLI API) will be mentioned below.

Name restrictions

• Case-insensitive linkers will have problems with external identifiers that differ only in case.
• There is a restriction on how many characters of an external identifier name a linker must support.¹⁰
• Identifiers that begin on _ or __ are reserved for the C implementation and may not be used.
• Some additional prefixes are reserved and may not be used: str (string functions, string.h), E (operating system error numbers, errno.h).

Libraries tend to include package membership information (e.g. t_open, t_bind, etc. of the TLI network interface library) to omit name collisions¹².

However, it will be impossible to find small unique package prefixes¹³.

File names

Filesystems (in which the source files are stored) may or may not be case-sensitive¹⁴. In the later case, one cannot save e.g. Main.c and main.c in the same directory.

The recommended character set for file names, valid on most systems, is rather small: letters, digits, .-_ and maybe ~@+%,, reasons being

• some characters are used by filesystems (/\:;)
• some characters have the meaning of quotes (in scripts or shells) ("'\`)
• some characters are delimiters in shells (blank, tab)
• some characters are meta characters in shells (<>()[]{}$=`;&|^*?#!)
• some characters depend on a non-ASCII character set

A package prefix is considerable with header files to avoid namespace problems (a bad example being external header files named error.h or types.h).

Compiler warnings

Note that there may exist differences in the number of warnings issued between an non-optimizing compile (cc -O0 ...) and an optimizing compile (cc -O3 ...). Of course both compiles should be satisfied.

Further, extended syntax-check programs such as lint should be used permanently.

The time saved by using the compiler's hints is typically more than the time spent to keep the sources warning-less.

Some third party libraries or even compilation systems(!) may include header files that produce annoying warnings when compiled with the highest warning level. I recommend to encapsulate the offending interface declarations in a code layer that meets the warning-less requirement

If the source code is to be distributed and will be used on a variety of systems, it should be revised for warning-less compile on several compilers and/or computer/operating systems. You may also want to do cross-compiles.

Compiler warnings may be a hint of incompatibilities. E.g. the warning "possible bad alignment" may not be an error on CISC CPU architecture systems, but will be one on RISC systems.

Compiling C code as C++ code may reveal C/C++ incompatibilities¹⁵, specially with assignments from and to void*¹⁶.

Style warnings

The warning "assignment in conditional expression" can be avoided by using while((p = next()) != 0) instead of while(p = next()).

The warning "conditional expression is constant" can be avoided by using for(;;) instead of while(1).

The "unreferenced parameter" warning is a tough one in the C language¹⁷. Suggestions were: casting to void (does not suppress the warning on all compilers) and self assignment (looks weird and lets me think of a "statement has no effect" warning).

Asserts (assert.h) may produce "statement has no effect" warnings in the release version. This one seems to be tough.

The "comparison of signed and unsigned values" warning appears if signed and unsigned values are mixed in a less/greater expression. One approach is not to use unsigned values at all. strlen() may unfortunately require an int cast.

Helper tools

lint is a traditional Unix development tool, originally designed for K&R1.

It allows

• to catch some of K&R1 pitfalls (insufficient type checking, missing declarations)
• to check inter-module issues (inconsistent interface declarations, e.g. char p[] vs. extern char* p)
• to find globally unused functions and variables
• to find dead (unreachable) code (which is usually an error)
• to check for false or missing arguments to printf() or scanf()
• to check static array's bounds
• to catch inconsistent function use (e.g. ignoring return values sometimes)

Simple metrics count e.g. the

• number of source code lines
• number of lines of code (LOC, leaving out empty lines and comments)
• number of comments¹⁸
• number of statements
• ratio of comments per statement

Advanced metrics can count function points, express code complexity (e.g. statements per function, nesting, number of cross-references, etc.).

Even more advanced metrics may try to track changes in micro architecture¹⁹, changes in interfaces and the like, as the project development goes on. This may be accomplished together with configuration management tools.

Assertions

Assertions can be used to check the internal program logic and a correct program flow.

Drawbacks are:

• They're expensive to code.
• Their use might not be systematic (because manually created).
• The code may get harder to read.

Release versions typically do not contain the assertions. Beta versions may or may not contain the assertions.

Runtime checkers

The use of such tools may be time consuming since the program may run factors slower. The tool may not be able to distinguish between e.g. memory leaks (bad) and reusable buffers that won't be freed (a valid design decision).

Samples are: purify, electric fence (dynamic memory checks only).

These applications may be used in automated testing suite.

Code complexity

• Code can become unreadable.
• Complicated expressions may require a operator precedence lookup, based on the assumption that one does not have all of the precedences memorized²⁰.
• Source code debugging doesn't show intermediate data.
• Expressions need to be wrapped to a second line or the line will be extraordinary long.

You should not avoid using temporary variables in order to enhance performance. Temporary variables can be optimized away to lead to the same code that was expected from the complicated expression (if the compiler is powerful enough).

One drawback of nested expression was the warning "assignment in conditional expression" with if(p = malloc(size)). The warning can be avoided by using parentheses or by separating statements: p = malloc(size); if(p). This may additionally make debugging easier.

Redundancy

Redundant code is harder to maintain and increases the probability of introducing defects. Code with many redundancies is harder to read.

You might consider implementing a more general function instead²¹.

If performance is the problem, use macros or an optimizing compiler that inlines the functions (preferred).

Determinism

Searching for bugs that show non-deterministic symptoms is an unpleasant task at best.

You may consider to assign a freed pointer 0²².

Modularity

No extern declaration must appear in C files. They belong in commonly included header files.

I tend to design one header file for each C source file. If several modules are linked together to a library, a new external header file may be created that declares all extern functions. Alternatively, all of the extern functionality can be encapsulated in one source file²⁵. Its according header then becomes the external header.

There are very few reasons to include static definitions in header files.

There is in my opinion no reason to include static function declarations in header files. They belong in the source file that implements the functions.

Header files

Header files must be included by both the implementing module and the calling module(s). Note that the inclusion in the implementing module is not enforced by the compiler and the linker will link independently of actual function parameter types²⁶.

As mentioned above, it's wrong to declare static functions in a header file or to not define functions as static that are only used in one module.

Header files should use include guards to enable²⁷ (intended or unintended) multiple inclusion²⁸:

#ifndef header_h
#define header_h
...
#endif

Header files must not be included by an absolute path (e.g. /usr/include/header.h), paths can be specified in compiler options (-L/usr/include). Using relative paths is correct (e.g. sys/header.h), however using .. seems confusing (e.g. ../header.h).

Never use the extern keyword in source files, use it only in header files.

Resources

Resource data should carry the const modifier, so it can possibly be put into a read-only data section²⁹. This allows instances to share the resource memory and the operating system does not need to allocate virtual memory paging space for it.

Code order

There are some aspects to consider about the order of the code in a source file:

• Using Pascal style makes it unnecessary to track function interface changes in the prototypes.
• A compiler may chose only to inline functions on high optimization levels and if they have been defined before.
• C style sources seem to be easier to read since going from the start of the file to the end is much more like the actual program flow compared to Pascal style.

Error handling should typically be done without delay, e.g.

fp = fopen(file, "r");
if(fp == 0) return -1;
process(fp);

fp = fopen(file, "r");
if(fp != 0) process(fp);
else return -1;

• don't use conditional compiling at all
• conditionally include only a few macros and include directives
• conditionally include large parts of code

Nested conditional compiles seem to confuse further.

However, suitable editors can display uncompiled parts of the code in comment font type³¹ and even fold it, to make sources more readable. There are tools available to remove the unused conditional parts³².

Alternatives to conditional compiling are including one of different header files (with the -I compiler option) or linking one of different libraries (with the -L compiler option) or both. In development, you may chose to create a set of subprojects and include and link one of them.

Conditional use of parts of code, header files, libraries or subprojects is often used to encapsulate platform specifics.

Code nesting

You may want to design a separate local function that implements the inner part of a loop, to avoid deep nesting. This may make it easier for a compiler to optimize the code³³.

I would say that no more than two levels of nesting should be used.

Designing small functions and using return on error cases instead of adding a layer of if/else further reduces nesting and makes code more readable (in my opinion).

Scope

• application scope
• file scope
• function scope
• block scope

Choosing the scope of a function, variable or type is one of the most important micro architecture instruments.

Generally, scope should be chosen as narrow as possible.

Scope of functions

A narrow function scope encapsulates code.³⁴

Scope of variables

Typically, there is no overhead (stack pointer operations) involved with block scope variables, space for the deepest possible block allocation gets reserved at function entry.

Application scope leads to global variables, which generally should be avoided. Use functions to access the data (getX() and setX()) instead³⁶.

Application scope or file scope (as well as static data in functions) lets the functions that access the data only be useable by a single thread³⁷.

A reference to a calling functions buffer should be used instead of global or static data to avoid multithreading problems and buffer overwrite problems (e.g. as with localtime()).

Scope of types

Don't redefine types in file scope, use common header files instead.

Scope of macros

However, macro encapsulating code fragments as

#undef m
#define m ...
...code...
#undef m

Limiting macro scope is a bit obscure.

Error prone constructs

As a sample, Java doesn't pose problems with explicit casts, array sizes, buffer sizes, macros and less problems with error checking (through the use of exceptions). Lisp e.g. doesn't pose problems with number ranges.

Explicit casts

Use explicit casts as rarely as possible³⁹. It's good to think whether an explicit casts is necessary and what the compiler will do with it.

The C language allows implicit conversions from T* to void* and vice versa⁴⁰. There is no explicit cast needed in C to convert from void*. malloc() is a sample of an often used function that returns void*.

Type size

int size limits the range of numbers you can use⁴¹. Check if e.g. 31 bit (signed int) is enough for your problem domain.

Array size

• 32
• SIZE (a macro used for the array definition)
• sizeof(a)/sizeof(*a)

This rule should be strictly followed if the input size is an external (and hence uncontrolled) property (e.g. a line length with gets()).

Buffer overflows can

• corrupt adjacent data
• corrupt the stack frame (if on the stack)
• corrupt malloc internal data (if on the heap)

A sample of a corrupted stack frame is a program that crashed (on a little endian system), leaving a core⁴². Because of the overwritten stack, the debugger that was used to examine the core (sdb) was unable to display a backtrace and just displayed the message "cannot get_text from 0x63697245", which confused on the first look, but was a good hint that upon returning from the corrupting function, the program tried to jump to nil.

One problem is to guess how much buffer size a sprintf() will require. However, sprintf() allows to specify maximal lengths of spliced fields to limit the output string size (e.g. sprintf(buf, "...%.*s...", sizeof(buf)-1-..., p).

Note that buffer overflows are security problems. Overwriting stack based buffers (while knowing the affected program and the system it runs on very well) can be used to insert manipulated function caller addresses and hence execute malicious code⁴³.

Macro parameters

#define sqr(x) x*x
sqr(a+b)

#define sqr(x) ((x)*(x))
sqr(a+b)

#define max(a,b) ((a)>(b)?(a):(b))
k = max(i++,j++);

A typical sample is the sign extension from character to integer:

char* p; ...
printf("0x%02x", *p);

printf("0x%02x", (unsigned char)*p);

Lint's warning "return value sometimes ignored" may help to identify offending code locations.

A classical C language programming error is not to check malloc() for nullpointer return⁴⁴.

Sequence points

*p++ = *p++ = 0;

*p = 0;
p++;
*p = 0;
p++;

*p = 0;
*p = 0;
p++;
p++;

It would be nice if undefined behavior through missing sequence point definition was generally diagnosed by compilers⁴⁵.

Optimizer errors

There are two considerations:

• Do most of the development without optimization.
• Look at the assembly output if you suspect errors.

Define the numbers as constants, macros⁴⁶ or enums outside the functions.

They should especially not appear in the code if they're meaningful for limitations or performance of an algorithm (e.g. if they limit some input size).

Counterexamples are

• buffers that starts at some size and increase if needed
• values that are encapsulated deep in some implementation of an algorithm

Use as few hardcoded values as possible. Don't use static sized tables of data, since they are almost never appropriate.

Don't generate any hidden dependencies among constants. Define constants by means of the constants they derive from.

Numeric constants are hard to understand if they're at the same time not commented and not composed of other named constants. Compilers are quite able to do arithmetics at compile time, use them.

Sample: if you need a buffer to hold a string representation of an integer, define its size in terms of INT_MAX or sizeof(int). E.g.: sizeof(int)*5/2+3⁴⁷ (assuming 8 bits per byte).

Unsigned numbers

Typically you will only gain one of 32 or 64 bits, which can often be neglected. Again: know your problem domain. If you need more than 31 bits in an application, you may want to switch to 63 bits or bignums.

The C language will also not indicate an exception if you subtract a larger unsigned number from a smaller unsigned number, so you can't make your programs more robust by means of using unsigned values.

Using signed and unsigned values leads to ambiguities when comparing or adding them.

Longs, shorts

Traditionally, long and short (or unsigned long, unsigned short) were used (together with htonl(), ntohl(), htons(), ntohs()) in implementing low-level network protocols, such as UDP-based application protocols⁵⁰. The assumption was that C implementations define a long to be exactly 32 bits, which is however not defined by the C language standard.

Use ASCII representations of numbers, when you write them to file or network, in order to be system architecture independent (size, byteorder, padding)⁵¹.

Besides using htonl() and ASCII, there exist some architecture independent data representation libraries like XDR⁵². However, ASCII representations seem easier to debug, because human readable.

Using shorts may save significant space in large arrays. However, if the problem domain changes, shorts may become too small. Conversions from shorts to ints and back may also bring some computational overhead.

Know also that unexpected alignments may occur if you mix shorts and longs. Sample: struct {short a; long b;}; will most probably be eight bytes of size, not six⁵³.

Floats

Reasons being

• Integers may be more adapted to the discrete nature of a problem.
• Integer arithmetics are faster than float arithmetics (if that matters).
• Not using floating point numbers results in smaller executables on systems that require floating point handling routines⁵⁴ and link them statically.

Many problems are solvable without using floats. E.g. a typical hashtable high-water-mark of 0.75 may be expressed by a ratio and handled by integer arithmetics: if(4*items > 3*size) ...

Avoid single precision float. Use double.

If you have to deal with single precision floats on file, then encapsulate the code that deserializes (reads them back).

If space counts, you may consider to use normalized numbers, that are adapted to the problem domain (e.g. shorts signifying 1000th).

Parameter types

Use int main(int argc, char** argv) instead of int main(int argc, char* argv[]). The internal semantics of a parameter are that of a variable declared as char** argv, not char* argv[].

Variable arguments

Some compilers (and e.g. lint) warn of wrong arguments supplied to the variable argument function families printf() and scanf(), which are part of the standard C library.

Portability types

Some standard library functions might even get inline expanded (memcpy()), so there's probably no performance problem.

You should use stuff that's offered. E.g. strerror() will tell a lot about the origin of an error reported by the operating system. Not using it will leave the user and support group clueless.

Don't use gets() and the scanf() family for safety (buffer overflow crashes or program corruption) and security reasons (buffer overflow exploits). Use fgets() respectively fgets();strtok();atoi(); etc. instead.

NULL macro

• if(!p) ...
• if(p == 0) ...
• if(p == NULL) ...

One could assume that compilers know the CPU registers better than the C programmer does, since they are the interfaces to the register-using assembly languages.

Also, compilers are free to ignore the register keyword (and often will⁵⁷).

Auto

Rarely, auto was used to emphasize that a function variable needs explicitly to be automatic. E.g. in a recursive function in which some variables may be modified to be static (to save stack space). However, the latter is bad practice since it is not multithreading save⁵⁸.

Goto

Most of the control flow problems can be solved by using additional layers of local functions (that need not imply overhead). Use return to jump out of them. Introducing function layers may enhance modularity and code encapsulation.

Appreciate also break and continue instead of goto.

Multiple returns

I see multiple returns as a good micro design construct. They allow function code to be less deeply nested.

Obscurities

Don't use

f() && g();

if(f()) g();

Don't overuse the comma operator.

Topics left out

• the pros and cons of the ternary operator ?:⁵⁹
• the pros and cons of polymorphic function arguments (e.g. declaring a parameter as a long and casting all possible arguments to it)
• the use of a function parameter to hold separate information (e.g. putting two shorts into a long parameter)
• the pros and cons of code optimization and when and where to deploy such⁶⁰
• recommendations on how many lines of code per function and module⁶¹

• filters can be used to adjust source code⁶² (e.g. indent)
• syntax coloring editors can be used to adjust source code (e.g. xemacs)
• a programmer can often easily adapt to a style

However, independently of the indent style you use,

• be consequent
• try not to make assumptions about other editors tabulator settings

Not all editors can preserve tabs or blanks⁶⁴. In a worse case, only the indentation of changed lines in a source file is converted.

Tabulators can also become victims of branch merge tools (which are part of revision control software).

Braces

If the opening and/or closing braces are on a line of their own, they can be adjusted to the indent level of the outer block or to that of the inner block or (halfway) in between.

The use of the above styles can differ between code (functions) and data (structs, unions, array initializations) and can differ between top level code braces (functions) and function level code braces (do, else, for, if, switch, while).

Braces may or may not be omitted in control blocks if the block covers one or zero statements⁶⁵.

Labels

Goto labels can be adjusted to the left margin (i.e. top level block), one indent level less than the next statement, or on the same level as the next statement. The first two styles are more readable.

Be consequent about placing the labels.

Blanks

Be consequent about using blanks between tokens.

Trailing blanks and tabulators change only the meaning of trailing backslashes (e.g. in C++ style singleline comments⁶⁷ where they're legal and have a semantic). Using trailing blanks and tabulators in this context is dangerous, since editors may be inaccurate in preserving them.

Comments

You might include some evident information in every C source file:

• a short description of functionality
• a revision date (maybe generated by version control)
• an author
• maybe a copyright
• maybe the revision history (unless maybe managed by version control)

Don't comment the obvious.

Don't use comments as substitutes for speaking identifier names.

Comments can have the semantics of a tool directive (e.g. /*LINTED*/, /*ARGSUSED*/, /*NOTREACHED*/ or /*EMPTY*/ for Lint). They might or might not be used.

Block comments

You may consider to put an empty line between blocks to make them a bit more readable. You may generally consider consequent spacing.

In the C language (unlike the C++ language⁶⁹), a block has two parts: a variable definition part and a code part. These two parts should be separated by a blank line to make them more readable.

I would not recommend to comment the closing brace of a block. A suited editor typically lets the user jump to the corresponding opening brace. The same applies for #endif.

Conclusions

I hope to have given a thorough insight into most aspects⁷⁰ that are essential in establishing C programming language guidelines.

Footnotes

⁷⁰ Of course, there's always more.

References

[BK/DR,1988] The C Programming Language, B. W. Kernighan, D. M Ritchie, Prentice Hall, 2nd Ed. 1988

[BS,1997] The C++ Programming Language, B. Stroustrup, Addison-Wesley, 3rd Ed. 1997

Index

Keywords: C programming language coding guidelines, C coding guidelines, C coding standards, C rules, C recommendations, coding in C