Section 3. Coding Style Guidelines

: The guidelines to follow when writing code are here to make the entire project look as though it has been written by only one developer. They are intended to keep the code easy to read and understand. Many of the documentation guidelines are in place to keep the generated documentation consistent and helpful for development of the project. These guidelines are intended to be as minimal as possible while still keep the project as consistent as possible. Other ideas to improve code readability and usefulness are encouraged to be shared with the rest of the project. By no means are these guidelines meant to make its developers feel restricted in their coding styles!

: The Covered project uses a combination of standard C comments embedded in the code as well as special comments that are parsable by the Doxygen utility. The Doxygen tool is used to generate all of the development documentation for the project in HTML and Latex versions. This allows the documentation to be viewable via an HTML browser, Acrobat reader, LaTeX viewers (and other related viewers), and embedded in the code itself. For documentation on the usage of Doxygen, please see examples within the Covered project and/or check out the available documentation at the Doxygen website:

: The following are a list of guidelines that should be followed whenever/wherever possible in the source code in the area of documentation.

All header files must begin with a Doxygen-style header. For an example of what these headers look like, please see the file vsignal.h
All source files must begin with a Doxygen-style source header. For an example of what these headers look like, please see the file vsignal.c
All files should contain the RCS file revision history information at the bottom of the file by using the Log keyword.
All defines, structures, and global variables should contain a Doxygen-style comment describing its meaning and usage in the code.
Each function declaration in the header file should contain a Doxygen-style brief, one line description of the function's use.
Each function definition in the source file should contain a Doxygen-style verbose description of the function's parameters, return value (if necessary), and overall description.
All internal function variables should be documented using standard C-style comments.

: The most important guideline is to keep the code documentation consistent with other documentation found in the project and to keep that documentation up-to-date with the code that it is associated with. Out-of-date documentation is usually worse than no documentation at all.

: The following are a list of guidelines that should be followed whenever/wherever possible in the source code in the area of source code.

Avoid using tabs in any of the source files. Tabs are interpreted differently by all kinds of editors. What looks well-formatted in your editor, may be messy and hard to read in someone else's editor. Please use only spaces for formatting code.
Make sure that all files contain the GPL header information (see any source file to get a copy of this license agreement).
All defines and global structures are defined in the defines.h file. If you need to create any new defines and/or structures for the code, please place these in this file in the appropriate places.
For all header files, place an

 #ifndef __<uppercase_filename>__
 #define __<uppercase_filename>__
 ...
 #endif

: The most important guideline is to keep the code consistent with other code found in the project as it will keep the code easy to read and understand for other developer's.

Go To Section...