root/library/doc/tutorial/codingrules.dox @ 680

/*!
\page codingrules Coding Rules (Mostly inherited from IT++)

In the following sections we describe the naming conventions which are
used for files, classes, structures, local variables, and global variables.


\section cr_variables Default Naming Rules for Variables

Generally, variables are named using lower-case letters and words are separated using
under-score. But there are many exceptions, for instance abbreviations or classical 
matematical notations. Therefore, coding rules for variables are quite free. Examples:

<ul>
<li> \c `FFT_size' </li>
<li> \c `initial_RV' </li>
<li> \c `my_variable' </li>
</ul>

\section cr_files Default Naming Rules for Files

Files are named using lower-case letters and words are separated using
under-score. If an abbreviation is inevitable within file name, it is written with 
lower-case letters. 

Source files are named using <tt>`.cpp'</tt> suffix, whereas header
files end with <tt>`.h'</tt> extension. Examples:

<ul>
<li> <tt>`my_file.h'</tt> </li>
<li> <tt>`user_info.cpp'</tt> </li>
</ul>

\section cr_file_templates Form of the source files

For all the library classes, both header file `[filename].h' and source file 
`[filename].cpp' should be implemented. And the following few rules should be 
respected   

<ul>

<li> if possible, each `\#include ... ' dircetive should be located within the `.h'
file, one obvious exception is the case of `\#include "[filename].h"' written in 
`[filename].cpp' </li>

<li> firstly, system headers should be included (i.e. those with brackets 
`\#include \<system_header_name\>'), other headers (like `\#include "my_header_name.h"') 
should follow (this rule leads to the faster search of an error on some 
compilators) </li>

<li> source code itself should be placed in the `.cpp' file, `.h' should 
contains only class declarations and documentation (this rule has a few exceptions like
 inline functions, templates and some extremely short function bodies)</li>

</ul>

Rules considering formatting of the source code itself are stored in the 
file /system/astylerc, which is a configuration file for code formating 
utility named ASTYLE. To apply them, download the proper version from 
its web page http://astyle.sourceforge.net/     

\section cr_functions Default Naming Rules for Functions

Function names are named using lower-case letters and words are
separated using under-score. Abbreviations, when used in function
names, are also written with lower-case letters. This rule applies
both to stand-alone functions as well as to member functions of
classes. Example:

<ul>
<li> <tt>int my_function_name(int a, int b)</tt> </li>
</ul>


\section cr_specialfunctions Convention for sensitive functions

For efficiency, some functions may return pointers to internal variables.
Such functionality is indicated by underscore as the first letter in the
the name.

<ul>
<li> <tt>mat* _internal_matrix()</tt> </li>
</ul>


\section cr_classes Default Naming Rules for Classes and Structures

Each new word in a class or structure name should always start with a
capital letter and the words should not be separated. Abbreviations are 
written with capital letters. Examples:

<ul>
<li> \c `MyClassName' </li>
<li> \c `MyStructName' </li>
<li> \c `OFDM' </li>
</ul>


\section cr_classes_functionality Default Functionality of Classes

All classes that are configured by input parameters should include:

<ul>
<li> default empty constructor </li>
<li> one or more additional constructor(s) that takes input parameters
and initializes the class instance </li>
<li> setup function, preferably named \c `setup' or \c
`set_parameters' </li>
</ul>

Explicit destructor functions are not required, unless they are
needed. It shall not be possible to use any of the other member
functions unless the class has been properly initiated with the input
parameters.

*/