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///////////////////////////////////////////////////////////////////////////////