Coding Guidelines
Generic Guidelines
File Basics
<- ^ ->
<< ^^ >>

File Names

File Suffixes
c "C" language source
cpp C++ source
def DLL exports definitions
h C or C++ header file
rc resource source
rgt registry
Lower-case letters and numbers only All characters in the name and suffix should be lower-case letters and numbers. Never try to use the capitalization of a character to denote special meaning (e.g., using an upper-case 'C' suffix to denote C++ files, use "cpp" instead).
Start name with Letter The first character in a file's name should always be a letter (e.g., "a" through "z").

Reasonable Limits

96 columns max Source lines should be limited to 96 columns for all source files. Lines that are excessively long due to deep indenting are often symptomatic of poorly organized code and should be reworked.
3,000 lines max Although there is no real maximum limit to the number of lines of code for source files, files with more than about 3,000 lines of code are cumbersome to deal with.
95 printing ASCII characters The character set used for all source file contents should be restricted to the 95 printing ASCII characters.

Standard File Contents

Always prefix file with standard copyright notice and revision history

 The file should always begin with the standard copyright notice comment block. There should also be a revision history comment block near the beginning of the file, describing all changes to the file.

The easiest way to setup a file for the standard comments is to use the development template files described below.
Use File Templates Use the file templates to create all new source files. Copy the file and rename it according to the file name and suffix conventions.

The templates are available at "L:\bldtools\templates"

c.c C source file
c.h C header file
com_if.h COM interface declaration header file
com_imp.cpp COM class implementation source file
com_imp.h COM class implementation header file
cpp.cpp C++ class source file
cpp.h C++ class header file
#include <file.h> (angle brackets) for System files only Only use the angle bracket form of include for C or C++ standard include files (like stdio.h or strings.h). Don't consider the include files that you created for your application as standard or system. Unless you are writing the C compiler then your application's include files should use the quote form of include. Some compilers will look for the #include <file.h> only in the system/compiler directories. They provide no command line or configuration method of changing this behavior on a project or application basis.
System headers before your application headers Specify standard/system header files before your application's. This will highlight conflicts early in a porting effort. Also remember that it is taboo to modify system header files. You are not porting the system to your application.

The only exception to putting system header files before your application's are the precompiled header file and the file "machine.h" which identifies the machine upon which your application is currently being compiled. This is important since some header files may need to be conditionally included.
Avoid directory paths in #include Never specify directory path information in an include statement. Or if a path is required on some systems then the include statement should be defined as conditional and treated as non-portable.

Use make or build definitions to identify the locations of include files. If the path is being used because the file's name is a duplicate of some other include file, then change the name of the include.

Header Files

Single inclusion macros A Good practice for header files is to define a preprocessor symbol that identifies that the include file has already been included. By doing this redefinition errors can be avoided.

filename.h

#ifndef _H_filename
#define _H_filename
/* ... */
#endif /* _H_filename */

A valid alternative would be

#ifndef _filename_H_
#define _filename_H_
/* ... */
#endif /* _filename_H_ */

filename.inl

#ifndef _INL_filename
#define _INL_filename
/* ... */
#endif /* _INL_filename */

This also prevents users of include files from having to know what files are being included. However, if an include file is needed by a function, the programmer should not depend on the knowledge that another include file includes it. In other words, if a structure is needed make sure that the include file in which it is declared is directly included in the C source file. This is also true for other include files.

One thing that should be avoided is using double underscores at the beginning and / or ending of the name. According to the ANSI C and C++ standards, double underscores are reserved and should only be used by the compiler for predefined preprocessor variables (e.g., __FILE__, __LINE__, __DATE__, etc.). So in other words names like __filenameH__ are invalid.
Self sufficient header files That means that any of the include file dependencies that an include file has should be resolved by the include file itself. Do not require an API user to include another file to resolve a declaration required by your include.

One way to check this is create a source file that includes one header file. If there are any undefined, or undeclared type errors then you need to add the appropriate header files to your header file.
Never include executable code Include files should never define executable code.

(#define macros, C++ inline functions and templates are not considered to be executable in this respect)
Limit header file contents The contents of header files should be carefully limited. The guiding principle is: if it is not needed by multiple files then do NOT put it in a header file.

Another principle is: a place for everything and everything in its place. In other words, make sure that only related items are in the same include file. A miscellany header file becomes a major maintenance headache.
<- ^ ->
<< ^^ >>
Last modified: 07 Jul 2008
copyright 2004 Bear Consulting Group