1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
|
<!doctype html public "-//W3C//DTD HTML 4.0 Transitional//EN" "http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD>
<TITLE>nevrax.org : docs</TITLE>
<LINK REL=stylesheet TYPE="text/css" HREF="http://www.nevrax.org/inc/css/nevrax.css">
<link href="doxygen.css" rel="stylesheet" type="text/css">
</HEAD>
<BODY MARGINHEIGHT="0" MARGINWIDTH="0">
<!-- uplinks -->
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0>
<TR>
<TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
<TD WIDTH=140 BGCOLOR=#dddddd><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="16" BORDER=0 ALT=""></TD>
<TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
<TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle> <A CLASS=uplinks HREF=http://www.nevrax.org><b>Home</B></FONT></A> </TD>
<TD><IMG width=6 height=14 SRC="http://www.nevrax.org/inc/img/reddots.gif" ALT="#" VSPACE=2 HSPACE=2 BORDER=0 ></TD><TD VALIGN=middle> <A CLASS=uplinks HREF=http://www.nevrax.com><b>nevrax.com</B></FONT></A> </TD>
</TR>
</TABLE>
<!-- banner Nevrax -->
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 WIDTH=100%>
<TR><TD BGCOLOR="#000000" BACKGROUND="http://www.nevrax.org/inc/img/black_banner.jpg"><A HREF="http://www.nevrax.org"><IMG SRC="http://www.nevrax.org/inc/img/nevrax.gif" WIDTH="170" HEIGHT="45" BORDER=0 ALT="Nevrax" ></A></TD></TR>
</TABLE>
<!-- main table -->
<TABLE CELLSPACING=0 CELLPADDING=0 BORDER=0 height=100%>
<TR>
<TD WIDTH=16><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="10" BORDER=0 ALT=""></TD>
<TD WIDTH=140 BGCOLOR=#dddddd VALIGN=TOP ALIGN=middle><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">
<!------ Begin Box ------>
<TABLE BORDER=0 CELLSPACING=0 CELLPADDING=0 BGCOLOR=black><TR><TD><TABLE border=0 cellspacing=2 cellpadding=0 width=120><tr><TD ALIGN=middle bgcolor=black>
<FONT COLOR=white FACE="sans-serif"><B>Nevrax.org</B></FONT></TD></TR><tr><td colspan=2 bgcolor=#FFFFFF>
<TABLE cellspacing=0 cellpadding=1 border=0>
<tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="Rubrique news"><img width=13 height=15 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-news.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/news/" TITLE="News">News</a></td></tr>
<tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Rubrique mail"><img width=15 height=11 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-mail.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/mail/" TITLE="Mailing list archive">Mailing-list</a></td></tr>
<tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Rubrique docs"><img width=14 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-docs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/docs/" TITLE="Documentation">Documentation</a></td></tr>
<tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="Rubrique cvs"><img width=13 height=17 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-cvs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/cvs/" TITLE="CVS Web">CVS</a></td></tr>
<tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Rubrique bugs"><img width=20 height=16 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-bugs.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/bugs/" TITLE="Bugtracking">Bugs</a></td></tr>
<tr><td ALIGN=middle><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="Rubrique license"><img width=18 height=12 hspace=5 border=0 src=http://www.nevrax.org/inc/img/picto-gpl.gif ALT=#></A></td><td><a class='linkbox' href="http://www.nevrax.org/GPL.php3" TITLE="License">License</a></td></tr>
</TABLE>
</TD></TR></TABLE></TD></TR></TABLE>
<!------ End Box ------>
</TD>
<TD WIDTH=15><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="16" HEIGHT="16" BORDER=0 ALT=""></TD>
<TD ALIGN=left valign=top><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="140" HEIGHT="10" BORDER=0 ALT="">
<!-- title -->
<TABLE background="http://www.nevrax.org/inc/img/redline.gif" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td>
<A HREF="http://www.nevrax.org/docs/"><img src="http://www.nevrax.org/inc/img/t_docs.gif" ALT="Docs" HEIGHT=20 BORDER=0></A>
</td><td><IMG SRC="http://www.nevrax.org/inc/img/pixel.gif" WIDTH="1" HEIGHT="1" BORDER=0 ALT="">
</td></tr></table>
<!-- block -->
<TABLE bgcolor="#dddddd" CELLSPACING=0 CELLPADDING=0 BORDER=0 width=100%><tr><td width=1% valign=middle><img width=6 height=14 hspace=2 vspace=2 src="http://www.nevrax.org/inc/img/reddots.gif"></TD>
<TD><B>Documentation</B></TD>
<TD ALIGN=RIGHT> </td>
</tr></table>
<!-- Generated by Doxygen 1.2.14 -->
<center>
<a class="qindex" href="index.html">Main Page</a> <a class="qindex" href="namespaces.html">Namespace List</a> <a class="qindex" href="hierarchy.html">Class Hierarchy</a> <a class="qindex" href="classes.html">Alphabetical List</a> <a class="qindex" href="annotated.html">Compound List</a> <a class="qindex" href="files.html">File List</a> <a class="qindex" href="namespacemembers.html">Namespace Members</a> <a class="qindex" href="functions.html">Compound Members</a> <a class="qindex" href="globals.html">File Members</a> <a class="qindex" href="pages.html">Related Pages</a> <a class="qindexRef" doxygen="_cgi:http://www.nevrax.org/cgi-bin/nel-search.cgi" href="http://www.nevrax.org/cgi-bin/nel-search.cgi">Search</a> </center>
<hr><a name="codinghowto"><h2>Coding and presentation conventions</h2></a>
<dl compact><dt><b>
Author: </b><dd>
Vincent Archer , Vianney Lecroart</dl><a name="introcode"><h2>Introduction</h2></a>
<p>
This document defines and formalises the presentation and redaction of all source files in the NeL platform. A strict adherence to these conventions is required to ensure a readable and understandable code.
<p>
<a name="filename"><h2>File naming</h2></a>
<p>
There are very few restrictions on file names and locations. The following rules are expected:
<p>
<ul>
<li>Files must end with the appropriate suffix:<ul>
<li>.<code>cpp</code> for ANSI C++ code<li>.<code>c</code> for ANSI C code<li>.<code>h</code> for included declarations<li>.<code>asm</code> for assembly-level files<li>.<code>dxt</code> for doxygen documentation source without code.</ul>
<li>Significant, english, file names. Length is not capped, but should be kept within resonable bounds.<li>No spaces or uppercase letters. If the name is composed of separate, discrete words, the underline character is used instead of space as the separator.</ul>
<a name="fileloc"><h2>File locations</h2></a>
<p>
A quick check of the CVS source directory will show how files are organised within the source tree. The sources are organised in two levels. The first level specifies which part of the platform the source belongs to
<p>
<ul>
<li><code>nel</code><li><code>client</code><li><code>server</code></ul>
The second level specifies which logical part the file belongs to:
<p>
<ul>
<li><code>network</code><li><code>ai</code><li><code>3d</code><li><code>database</code><li><code><a class="el" href="cf__lexical_8cpp.html#a95">file</a></code><li><code>system</code><li><code>misc</code></ul>
This applies to basic source as well as include files, who are in a separate include tree and never along their source code files. Thus, an include declaration would be
<p>
<div class="fragment"><pre><font class="preprocessor">#include "nel/misc/steam.h"</font>
</pre></div>
<p>
<a name="filehdrs"><h2>File header</h2></a>
<p>
All code files must begin with a specific header. The model of that header is defined in Headers.txt in the documentation directory. It is recommended that people include that file immediately when starting a new file.
<p>
<a name="basetype"><h2>Base types</h2></a>
<p>
<ul>
<li>Integral types<ul>
<li>The first letter specifies '<code><a class="el" href="driver__opengl__extension__def_8h.html#a383">s</a></code>' for signed integers or '<code>u</code>' for unsigned integers. It is not possible to specify a 'dont care sign' integer<li>The next three letters are '<code>int</code>'<li>The type ends with the number of bits used to represent the integral type, or nothing to specify an integer that is *at least* 32 bits wide<li>Examples: <code><a class="el" href="memory__common_8h.html#a7">uint8</a></code> (unisgned 8 bits integer), <code><a class="el" href="memory__common_8h.html#a12">sint64</a></code> (signed 64 bits integer), <code><a class="el" href="memory__common_8h.html#a14">sint</a></code> (signed integer of at least 32 bits)</ul>
<li>Classic types<ul>
<li><code>float</code> (32 bits floating point number, use is discouraged)<li><code>double</code> (64 bits floating point number)<li><code>bool</code> (an equivalent to the hypothetical uint1 type)<li><code>void</code> (empty type)<li><code>char</code> (ASCII character, not to be confused with uint8/sint8)<li><code>uchar</code> (Unicode character, on 16 bits)<li><code>string</code> (ASCII string)<li><code>ustring</code> (Unicode character string)</ul>
</ul>
As a general rule, the classic and sloppy use of <code>short</code> / <code>int</code> / <code>long</code> is proscribed, as is using a '<code>char</code>' to represent a 8-bit number, unless this is required to call an external API.
<p>
<a name="nameconv"><h2>Naming convention</h2></a>
<p>
All elements will be in their own namespace, which is short, in all uppercase, and consist of a two letter code (<code>NL</code> for NeL), followed by the directory name. Thus an element of the NeL 3D library will be declared in the <code>NL3D</code> namespace.
<p>
The following conventions are applied to names within these namespaces:
<p>
<ul>
<li>All names must include one or more english words which have relevance to the entity being named. If multiple words are used for a more descriptive naming, all words begin with an uppercase letter, the underscore character is not used to separate words (e.g. <code>Word</code>, <code>FullWord</code>, <code>ComplexQualifiedWord)</code><li>Class methods start with a lowercase character, e.g. <code>load()</code>, <code>store()</code>, <code>giveMoney()</code><li>Public attributes of a class start with an uppercase, e.g. Layer, Set, ResourceType<li>Private and Protected attributes of a class start with an underscore character, then an uppercase letter, e.g. <code>_State</code>, <code>_ResourceKind</code><li>Local variables and parameters start with a lowercase letter, e.g. <code><a class="el" href="cf__lexical_8cpp.html#a94">size</a></code>, <code><a class="el" href="driver__opengl__extension__def_8h.html#a364">x</a></code>, <code>i</code><li>Structures and Classes start with the uppercase <code>C</code> letter, then the name starting with an uppercase letter as well, e.g. <code>CTexture</code>, <code>CMyClass</code><li>Interfaces start with the uppercase <code>I</code> letter, then the name starting with an uppercase letter as well<li>Iterators start with the prefix '<code>It</code>' (uppercase I, lowercase t), then the name starting with an uppercase letter, e.g. <code>ItTexture</code><li>Other types, enums and the like are prefixed with an uppercase <code>T</code>, then the name.<li>Globals function and values are prefixed by their namespace values, then follow the standard conventions, e.g. <code>NLAI::createAttribut()</code>, <code>NLAI::ReactiveState</code><li>Preprocessor constants are in full uppercase, and consist of the namespace, an underscore character, then a name, with underscores as separators, e.g. <code>NLAI_MACRO</code>, <code>NL_OS_UNIX</code></ul>
Note that there is no difference between variables and constants.
<p>
<a name="codestyle"><h2>Coding style</h2></a>
<p>
<a name="indents"><h3>Indentation</h3></a>
<p>
A strong suggestion is to set your tabulation marks to 4 characters, rather than the usual 8. Indentation is always done using tabulations, never with spaces. Make sure your text editor does not replace tabulations with spaces.
<p>
If possible, function, members and variable lists should align the first character of all their names.
<p>
<a name="braces"><h3>Braces</h3></a>
<p>
Source code is written using a flat style. In this style, the opening and closing curly braces are placed on separate lines (never with code), and at the same indentation as the precedeing defining element, while the content of the block enclosed between the braces is indented once from the source. Your code source should look like this:
<p>
<div class="fragment"><pre><font class="keyword">class </font>CDummy
{
<font class="keywordtype">void</font> dummy (uint32 b)
{
<font class="keywordflow">if</font> (b == 0xDEADBEEF)
{
...
}
}
};
</pre></div>
<p>
<a name="commenting"><h3>Comments</h3></a>
<p>
Comments may use either the C++ style comments <code>//</code>, or the more classic C commenting method. If possible, the source must be heavily commented, and as many comments as possible must conform to the Doxygen commenting methods, to be extracted and reused as software documentation.
<p>
Comment "separators" will be made with a line of repeated star '<code>*</code>' characters. You should not use more than 50 stars to separate.
<p>
The practice of comment blocks, i.e. comments where each line begins and end with a star character, to create a "text block" is proscribed.
<p>
<a name="final"><h2>Final coding recommendations</h2></a>
<p>
Even if most of these are obvious recommendations, it is useful to restate these basic principles:
<p>
<ul>
<li>The use of <code>#define</code> must be restricted. Constants values and macro functions can be expressed directly in C++ using constants and inline functions, and do not require pre-processor definitions.<li>The '<code>using</code> <code>namespace</code>' declaration is proscribed in includes, unless it is in a well defined scope.<li>Include files paths, and all other file names should use the '<code>/</code>' character as the directory separator, for portability purposes.</ul>
<!-- footer -->
<BR><FONT Size=+5> </FONT>
</TD>
<TD WIDTH=15><IMG SRC=http://www.nevrax.org/inc/img/pixel.gif WIDTH=15 HEIGHT=15 BORDER=0 ALT=""></TD>
</TR>
</TABLE>
</BODY>
</HTML>
|
