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

Revision 613, 3.9 kB (checked in by smidl, 15 years ago)

documentation

Line 
1/*!
2\page codingrules Coding Rules (Mostly inherited from IT++)
3
4In the following sections we describe the naming conventions which are
5used for files, classes, structures, local variables, and global variables.
6
7
8\section cr_variables Default Naming Rules for Variables
9
10Generally, variables are named using lower-case letters and words are separated using
11under-score. But there are many exceptions, for instance abbreviations or classical
12matematical notations. Therefore, coding rules for variables are quite free. Examples:
13
14<ul>
15<li> \c `FFT_size' </li>
16<li> \c `initial_RV' </li>
17<li> \c `my_variable' </li>
18</ul>
19
20\section cr_files Default Naming Rules for Files
21
22Files are named using lower-case letters and words are separated using
23under-score. If an abbreviation is inevitable within file name, it is written with
24lower-case letters.
25
26Source files are named using <tt>`.cpp'</tt> suffix, whereas header
27files end with <tt>`.h'</tt> extension. Examples:
28
29<ul>
30<li> <tt>`my_file.h'</tt> </li>
31<li> <tt>`user_info.cpp'</tt> </li>
32</ul>
33
34\section cr_file_templates Form of the source files
35
36For all the library classes, both header file `[filename].h' and source file
37`[filename].cpp' should be implemented. And the following few rules should be
38respected   
39
40<ul>
41
42<li> if possible, each `\#include ... ' dircetive should be located within the `.h'
43file, one obvious exception is the case of `\#include "[filename].h"' written in
44`[filename].cpp' </li>
45
46<li> firstly, system headers should be included (i.e. those with brackets
47`\#include \<system_header_name\>'), other headers (like `\#include "my_header_name.h"')
48should follow (this rule leads to the faster search of an error on some
49compilators) </li>
50
51<li> source code itself should be placed in the `.cpp' file, `.h' should
52contains only class declarations and documentation (this rule has a few exceptions like
53 inline functions, templates and some extremely short function bodies)</li>
54
55</ul>
56
57Rules considering formatting of the source code itself are stored in the
58file /system/astylerc, which is a configuration file for code formating
59utility named ASTYLE. To apply them, download the proper version from
60its web page http://astyle.sourceforge.net/     
61
62\section cr_functions Default Naming Rules for Functions
63
64Function names are named using lower-case letters and words are
65separated using under-score. Abbreviations, when used in function
66names, are also written with lower-case letters. This rule applies
67both to stand-alone functions as well as to member functions of
68classes. Example:
69
70<ul>
71<li> <tt>int my_function_name(int a, int b)</tt> </li>
72</ul>
73
74
75\section cr_specialfunctions Convention for sensitive functions
76
77For efficiency, some functions may return pointers to internal variables.
78Such functionality is indicated by underscore as the first letter in the
79the name.
80
81<ul>
82<li> <tt>mat* _internal_matrix()</tt> </li>
83</ul>
84
85
86\section cr_classes Default Naming Rules for Classes and Structures
87
88Each new word in a class or structure name should always start with a
89capital letter and the words should not be separated. Abbreviations are
90written with capital letters. Examples:
91
92<ul>
93<li> \c `MyClassName' </li>
94<li> \c `MyStructName' </li>
95<li> \c `OFDM' </li>
96</ul>
97
98
99\section cr_classes_functionality Default Functionality of Classes
100
101All classes that are configured by input parameters should include:
102
103<ul>
104<li> default empty constructor </li>
105<li> one or more additional constructor(s) that takes input parameters
106and initializes the class instance </li>
107<li> setup function, preferably named \c `setup' or \c
108`set_parameters' </li>
109</ul>
110
111Explicit destructor functions are not required, unless they are
112needed. It shall not be possible to use any of the other member
113functions unless the class has been properly initiated with the input
114parameters.
115
116*/
Note: See TracBrowser for help on using the browser.