Sections in source code

As a software developer you will need to read code more often than you write it. Applying a consistent structure to your source code makes it easier to navigate and maintain your sources. Section headers are a great help in navigating your sources and also help in creating a consistent structure among co-workers. The order of sections is not trivial to get right. Sections may have dependencies: constants can refer to function declarations, function definitions refer to constants, etc. Sections also have a logical ordering: definitions of interface functions are more important than local functions and should be featured more prominently. The following snippets define the order of sections I apply to my sources. The ordering satisfies all possible/usefull dependencies (with one exception I know of) and prominently features the implementation of interfaces at the bottom of a source file. Due to dependencies it is not feasible to have the implementation of the interface at the top of the source file. Luckily, from a stylistic perspective (see Strunk & White), the bottom of the file makes sense. The include files at the top of the file gives a nice overview of the required interfaces. It may be necessary to add a macro before including a file, since the macro should be applied to that file as well. This is the one exception to the section dependencies I mentioned earlier. In this rare case I add the macro just before including the file, leaving the sections as is. This gives a nice visual clue that it is an exception rather than a rule. Header file (.h):

  1///////////////////////////////////////////////////////////////////////////////
  2// INCLUDES
  3///////////////////////////////////////////////////////////////////////////////
  4
  5///////////////////////////////////////////////////////////////////////////////
  6// MACROS
  7///////////////////////////////////////////////////////////////////////////////
  8
  9///////////////////////////////////////////////////////////////////////////////
 10// TYPES
 11///////////////////////////////////////////////////////////////////////////////
 12
 13///////////////////////////////////////////////////////////////////////////////
 14// FUNCTION PROTOTYPES
 15///////////////////////////////////////////////////////////////////////////////
 16
 17///////////////////////////////////////////////////////////////////////////////
 18// CONSTANTS AND VARIABLES
 19///////////////////////////////////////////////////////////////////////////////

Source file (.c):

  1///////////////////////////////////////////////////////////////////////////////
  2// INCLUDES
  3///////////////////////////////////////////////////////////////////////////////
  4
  5///////////////////////////////////////////////////////////////////////////////
  6// LOCAL MACROS
  7///////////////////////////////////////////////////////////////////////////////
  8
  9///////////////////////////////////////////////////////////////////////////////
 10// LOCAL TYPES
 11///////////////////////////////////////////////////////////////////////////////
 12
 13///////////////////////////////////////////////////////////////////////////////
 14// LOCAL FUNCTION PROTOTYPES
 15///////////////////////////////////////////////////////////////////////////////
 16
 17///////////////////////////////////////////////////////////////////////////////
 18// LOCAL CONSTANTS AND VARIABLES
 19///////////////////////////////////////////////////////////////////////////////
 20
 21///////////////////////////////////////////////////////////////////////////////
 22// LOCAL FUNCTIONS
 23///////////////////////////////////////////////////////////////////////////////
 24
 25///////////////////////////////////////////////////////////////////////////////
 26// EXPORTED CONSTANTS AND VARIABLES
 27///////////////////////////////////////////////////////////////////////////////
 28
 29///////////////////////////////////////////////////////////////////////////////
 30// EXPORTED FUNCTIONS
 31///////////////////////////////////////////////////////////////////////////////