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):

///////////////////////////////////////////////////////////////////////////////
// INCLUDES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// MACROS
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// TYPES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// FUNCTION PROTOTYPES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// CONSTANTS AND VARIABLES
///////////////////////////////////////////////////////////////////////////////

Source file (.c):

///////////////////////////////////////////////////////////////////////////////
// INCLUDES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// LOCAL MACROS
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// LOCAL TYPES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// LOCAL FUNCTION PROTOTYPES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// LOCAL CONSTANTS AND VARIABLES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// LOCAL FUNCTIONS
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// EXPORTED CONSTANTS AND VARIABLES
///////////////////////////////////////////////////////////////////////////////

///////////////////////////////////////////////////////////////////////////////
// EXPORTED FUNCTIONS
///////////////////////////////////////////////////////////////////////////////