Coding Standards

Compilation

Source code is written in C. The package follows the GNU build process, and uses autotools (autmake, autoconf, libtool).

By default, libraries are dynamically linked.

Full list of compilation options is obtained by :

./configure --help

For high performance (fast execution speed), use :

./configure_highperf

Modules

The code is arranged in modules. Source code, documentation and additional files for each modules are located in :

./src/<modulename>/

File / Directory	Content
./src/<modulename>/<modulename>.c	C source code
./src/<modulename>/<modulename>.h	Function prototypes
./src/<modulename>/Makefile.am	Makefile input
./src/<modulename>/doc/	documentation
./src/<modulename>/docdir/	extended documentation (optional)
./src/<modulename>/data/	module data file (optional)
./src/<modulename>/scripts/	high level scripts (optional)
./src/<modulename>/examples/	examples (optional)

Modules are compiled to object files, stored in ./libs/ (static and shared objects).

Documenting code

Github documentation

File README.md is the front page for documentation on the github site. It includes a link to ./index.md which is the top menu for the documentation, from which all documentation should be accessible.

Doxygen input files

Documentation is generated by doxygen from multiple sources:

• pages.dox top-level menu, which is the main page for doxygen-generated documentation. Contains entries such as @subpage page_pagename or @ref page_pagename that point to corresponding {#page_installation} tags in any of the doc/xxx.md files.
• markdown files (<filename>.md) in doc/ directories
• documentation contained in source code (.c and .h files)

Other documentation

Additional documentation that is not meant to be processed by doxygen (but can be linked from it) should be placed in directories named docdir. This can consist of pdf files, markdown file, or any other format.

Summary table

File / Directory	Github	Doxygen	Content
README.md	X		top level overview (application specific)
index.md	X		Main help index
pages.dox		X	top doxygen menu (application specific)
./doc/*.md		X	Generic documentation files
./docapp/*.md		X	Application specific docs
./src/doc/*.md		X	Generic documentation files
./src/docdir/*.md			non-doxygen documentation
./src/<modulename>/doc/*.md		X	Module documentation files
./src/<modulename>/docdir/*.md			Extended application documentation
-----------------------------—	-----—	----------—	----------------------------------------—

Additional details:

• README.md: file appears on github's front page, and contains an overview description of the software package.
• index.md: top menu for github documentation page. Contains links to help pages in other directories. Standard links include:
  • installation guide, usually in ./doc/ directory
  • user's guide, usually in ./src/<modulename>/doc and ./src/<modulename>/docdir directories
  • programmer's guide generated by doxygen: ./html/index.html

Documentation in source code (doxygen): conventions

Documentation should appear before each function in the .c and .h files, following these teamplates.

.h file

Download templatemodule.h

See corresponding doxygen documentation : templatemodule/templatemodule.h

.c file

Download templatemodule.c

See corresponding doxygen documentation : templatemodule/templatemodule.c