-3-
Considerable judgement is called for here. If defining large numbers of essentially-independent util-
ity functions, consider alphabetical order.
2.3. Header Files
Header files are files that are included in other files prior to compilation by the C preprocessor.
Some, such as stdio.h, are defined at the system level and must included by any program using the standard
I/O library. Header files are also used to contain data declarations and defines that are needed by more than
one program. Header files should be functionally organized, i.e., declarations for separate subsystems
should be in separate header files. Also, if a set of declarations is likely to change when code is ported
from one machine to another, those declarations should be in a separate header file.
Avoid private header filenames that are the same as library header filenames. The statement
#include "math.h" will include the standard library math header file if the intended one is not found
in the current directory. If this is what you want to happen, comment this fact. Don’t use absolute path-
names for header files. Use the <name> construction for getting them from a standard place, or define
them relative to the current directory. The ‘‘include-path’’ option of the C compiler (−I on many systems)
is the best way to handle extensive private libraries of header files; it permits reorganizing the directory
structure without having to alter source files.
Header files that declare functions or external variables should be included in the file that defines the
function or variable. That way, the compiler can do type checking and the external declaration will always
agree with the definition.
Defining variables in a header file is often a poor idea. Frequently it is a symptom of poor partition-
ing of code between files. Also, some objects like typedefs and initialized data definitions cannot be seen
twice by the compiler in one compilation. On some systems, repeating uninitialized declarations without
the extern keyword also causes problems. Repeated declarations can happen if include files are nested and
will cause the compilation to fail.
Header files should not be nested. The prologue for a header file should, therefore, describe what
other headers need to be #included for the header to be functional. In extreme cases, where a large number
of header files are to be included in several different source files, it is acceptable to put all common #in-
cludes in one include file.
It is common to put the following into each .h file to prevent accidental double-inclusion.
#ifndef EXAMPLE_H
#define EXAMPLE_H
... /* body of example.h file */
#endif /* EXAMPLE_H */
This double-inclusion mechanism should not be relied upon, particularly to perform nested includes.
2.4. Other Files
It is conventional to have a file called ‘‘README’’ to document both ‘‘the bigger picture’’ and is-
sues for the program as a whole. For example, it is common to include a list of all conditional compilation
flags and what they mean. It is also common to list files that are machine dependent, etc.
3. Comments
‘‘When the code and the comments disagree, both are probably wrong.’’ — Norm Schryer
The comments should describe what is happening, how it is being done, what parameters mean,
which globals are used and which are modified, and any restrictions or bugs. Avoid, however, comments
that are clear from the code, as such information rapidly gets out of date. Comments that disagree with the
code are of negative value. Short comments should be what comments, such as ‘‘compute mean value’’,
rather than how comments such as ‘‘sum of values divided by n’’. C is not assembler; putting a comment
at the top of a 3−10 line section telling what it does overall is often more useful than a comment on each
line describing micrologic.
Recommended C Coding Standards Revision: 6.0 25 June 1990
