With a light touch, please...

C++ Source Code

• Use spaces, not tabs, for indenting. Two (2)spaces per indentation level. (Choosing tabs vs. spaces is a religious issue (see Parkinson's Bike Shed), but a lack of consistency causes everyone daily headaches when working with the code and source control system.)
• File paths used in #include statements should follow these guidelines:
  • Don't use up-relative ('..') path elements.
  • Use double-quotes for any library that is not considered part of the compiler system.
    • Example: DirectX8 is not delivered with the compiler. Use double-quotes.
    • Example: windows.h is delivered with VC. Use angle-brackets.
    • Counter-example: Make an exception for libraries that replace standard compiler vendor libraries. For instance, STLport replaces the standard C++ library components, so its headers are included via angle brackets.
  • Include SDx library headers using a leading path element that identifies the library.
    • Example: #include "psim/BasicTypes.h"
  • For third-party libraries that encourage it, use the leading path name element convention.
    • Example: #include "boost/limits.hpp"
  • Include other files from the same project without a leading path name element.
  • Take care to use the correct upper/lower case names for files and directories. Although Windows doesn't care, other systems do. (Unimportant for Windows-specific code.)
  • Use forward slashes, not backslashes, to separate path elements. VC will work either way, but other compilers probably will not. (Unimportant for Windows-specific code.)
• Write header files so that they are idempotent, i.e. so that they will work regardless of the environment in which they are included.
  • A header file should always include any other headers that it needs. (But not ones that it doesn't! Make good use of forward declarations to reduce compilation times.)
  • Always guard headers using the #if !defined(INCLUDED_MYHEADER_H) idiom. (For Windows-specific headers, #pragma once may be used in addition to this.)
  • Minimize dependencies on preprocessor symbols, and try not to define too many of them.
  • To ensure that your header file is complete and correct, the associated .cpp file should include it as the very first thing that it does. (An exception must be made when using precompiled headers in Windows-specific code.)
• When writing software that is part of a Windows DLL, functions often have to be marked for export or import. (This is preferable to using a .DEF file.) Usually, a preprocessor symbol is used to determine if the file is being included for a build of the DLL or for use by a client. A distinct symbol should be used for each library. VC6 already has a convention for this: MYLIB_EXPORTS is defined in DLL builds. For instance, PSIM_EXPORTS is defined when building the physical simulator DLL.

Build Configuration

For instance, project configuration settings in VC6.

• Use search path elements (for headers and libraries) that are relative to the current project's source directory, not absolute.

Windows-specific:

• When memory ownership is transferred across DLL boundaries, it's important that both sides are using a DLL version of the run-time library, otherwise run-time memory management errors occur.