IONF Coding Standards Document
v1.0
4/10/01
This is version 1.0 of the IONF Coding standards document.
Created 4/10/01 by David Paul (dpaul@vt.edu)
This file should be located in the IONF/doc directory of the IONF CVS repository.
For a good document on general coding standards, see http://www.apocalypse.org/pub/u/paul/docs/cstyle/cstyle.htm
The ideas put forth here are in addition to those contained in the above document.
Section 1
General structure
------------------------------
The following is the directory structure for the project:
IONF/doc
Contains documentation on the actual code, will possibly be split into subdirectories for each subsystem. Documentation should be either plaintext, RTF, or Microsoft Word format.
IONF/src
Contains project Makefile, along with compilation instructions(README), BUGS, TODO, etc.
The rest of the directories contain the source code, split into various subsystems.
IONF/src/adcs
IONF/src/orbital
IONF/src/comm
IONF/src/power
IONF/src/thermal
IONF/src/cdh
cdh would include the task manager, watchdog, etc. (Command and Data Handling)
Additional directories will be added as needed, however most files should fall into one of the above directories.
Section 2
File naming
------------------------------
Source files will be suffixed with '.c', header files with '.h'. Header files containing definitions for items in a source file should have the same name (minus the suffix) as the source file. File names should begin with capital letters, and each new word should be re-capitalized. School-specific files should be named "Filename_XXX.c" where XXX will be one of VT, USU, or UW.
In each file that is not school specific, sections that are school specific should be enclosed in #if/#elif/#else/#endif preprocessor blocks. The macros VT, USU, or UW will be defined, depending on which school is doing compilation. An example follows:
#if defined(VT)
..
/* VT-specific code */
..
#elif defined(USU)
..
/* USU-specific code */
..
#elif define(UW)
..
/* UW-specific code */
..
#else
#error Fatal: One of VT, USU, UW must be defined!
#endif
Section 3
Identifier naming
------------------------------
All identifiers that are not temporary and serve a definite purpose should be named in the following way:
- Each identifier will begin with a prefix identifying the system to which the identifier belongs. This prefix will always be followed by an underscore, followed by the identifier name.
- For Variables, types, and function names, the name following the underscore should be capitalized, and contain no underscores. Each new word should be re-capitalized.
- For constants (#defines), the identifier name should be all capitals and may contain underscores. All constants should be #defined in this way using understandable and intuitive names. note: it will be safe to assume that TRUE(1) and FALSE(0) will be defined somewhere in the program.
The prefixes will be as follows:
- Global type, constant, function, and data names should begin with the characters 'IONF_'
- ADCS -> 'ADCS'
- Orbital -> 'ORB'
- Comm -> 'COMM'
- Power -> 'POWR'
- Thermal -> 'THRM'
- cdh -> 'CDH'
Section 4
Commenting
------------------------------
No exact standard for this section will be set. By now, everyone should be familiar with good commenting style. Just be sure to comment every function and interface and provide useful comments where necessary. See for a good document on commenting: http://freshmeat.net/articles/view/238/
Section 5
Miscellaneous
------------------------------
CVS -
Whenever modifications are made to a file, provide a short description of this change, along with your name and the date in a comment at the top of the file. Also, be sure to give reasons when checking a modified file into CVS.
Pointer responsibility -
If dynamic memory must be passed/returned by a function, it is preferable to use a buffer allocated by the calling function as a parameter along with a parameter indicating the size of that buffer. Then it will be the responsibility of the calling function to release dynamic memory as well.
Library functions -
Be sure to always use "safe" functions as opposed to their "unsafe" variants. For example, always use strncpy instead of strcpy.
Editing format -
Use a tab stop width of 3 and use tabs instead of spaces when possible.
Compilation options -
All sources will be compiled with the -Wall option, and all warnings should be eliminated.