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
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
|
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<!-- Created by texi2html 1.64 -->
<!--
Written by: Lionel Cons <Lionel.Cons@cern.ch> (original author)
Karl Berry <karl@freefriends.org>
Olaf Bachmann <obachman@mathematik.uni-kl.de>
and many others.
Maintained by: Olaf Bachmann <obachman@mathematik.uni-kl.de>
Send bugs and suggestions to <texi2html@mathematik.uni-kl.de>
-->
<HTML>
<HEAD>
<TITLE>Crystal Space: Coding Style</TITLE>
<META NAME="description" CONTENT="Crystal Space: Coding Style">
<META NAME="keywords" CONTENT="Crystal Space: Coding Style">
<META NAME="resource-type" CONTENT="document">
<META NAME="distribution" CONTENT="global">
<META NAME="Generator" CONTENT="texi2html 1.64">
</HEAD>
<BODY LANG="" BGCOLOR="#FFFFFF" TEXT="#000000" LINK="#0000FF" VLINK="#800080" ALINK="#FF0000">
<A NAME="SEC645"></A>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_273.html#SEC644"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_275.html#SEC646"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_271.html#SEC637"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_271.html#SEC637"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_277.html#SEC648"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<HR SIZE=1>
<H2> 9.3 Coding Style </H2>
<!--docid::SEC645::-->
<P>
For consistency and ease of future maintenance, when working on Crystal Space
source code, please follow the following guidelines. Also be sure to read
important portability guidelines presented in the <CITE>Portability</CITE> section.
See section <A HREF="cs_273.html#SEC644">9.2 Portability</A>.
</P><P>
<OL>
<LI>
<EM>Indentation</EM>
<P>
Indent with two (2) spaces. If you use tabs then they must be interpreted as
eight (8) spaces. This means that you should not use the tab character for
indentation since that would indent by eight characters rather than two. Also
consider avoiding tabs altogether in order to eliminate tab-related problems.
Here is an example of proper indentation:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>void foo()
{
int a;
for (a = 0; a < 10; a++)
{
int b = bar();
if (a < b)
printf("Hello\n");
}
}
</pre></td></tr></table></P><P>
This example also illustrates how to place curly braces and where to add
spaces, for example `<SAMP>for_(</SAMP>' rather than `<SAMP>for(_</SAMP>', where `<SAMP>_</SAMP>'
represents whitespace in this context. Also add sufficient whitespace between
tokens.
</P><P>
<LI>
<EM>Class and Method Naming</EM>
<P>
Classes should be named in this fashion: <CODE>csThisIsAClass</CODE>. The name
starts with lower-case `<SAMP>cs</SAMP>' and has every word capitalized.
</P><P>
Methods and functions should be named in this fashion: <CODE>ThisIsAMethod()</CODE>.
Each word in the name is capitalized.
</P><P>
<LI>
<EM>SCF Interfaces</EM>
<P>
SCF interfaces always start with a lower `<SAMP>i</SAMP>', as in
<CODE>iThisIsAnInterface</CODE>. See section <A HREF="cs_134.html#SEC297">6.4 Shared Class Facility (SCF)</A>.
</P><P>
<LI>
<EM>Doxygen and Comments</EM>
<P>
Use Doxygen comments in header files to document classes, methods, and
functions. These comments are extracted with the Doxygen tool and HTML
documentation is generated from them.
</P><P>
<STRONG>Warning</STRONG>: Always use Doxygen comments for a class. If you fail to do so
then Doxygen will ignore comments for methods within the class itself.
</P><P>
A one line Doxygen comment uses three slashes (`<SAMP>///</SAMP>') rather than two as
is typical for normal C++ comments. Multi-line Doxygen comments are specified
with `<SAMP>/** <small>...</small> */</SAMP>' rather than `<SAMP>/* <small>...</small> */</SAMP>'. Here is an
example:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>/**
* This class represents a blue ball.
* Blue balls bounce higher than red balls.
*/
class csBlueBall
{
private:
// A private function, so no Doxygen comment here,
// but still commented for readers of the header file.
void PrivateFunction();
public:
/// This is the constructor which initializes the blue ball.
csBlueBall();
/**
* This is a multi-line comment.
* And this is the second line of the multi-line comment.
*/
void Deflate();
};
</pre></td></tr></table></P><P>
<LI>
<EM>Maximum Line Length</EM>
<P>
In general, lines in source code should be no longer than 78 characters. This
facilitates generation of hard-copy and works better with certain tools which
process code or text files.
</P><P>
<LI>
<EM>Multiple-Inclusion Protection for Headers</EM>
<P>
Be certain to insert multiple-inclusion protection in all header files. These
controls should take this form:
</P><P>
<TABLE><tr><td> </td><td class=example><pre>#ifndef __CS_FILENAME_H__
#define __CS_FILENAME_H__
<small>...</small>
#endif // __CS_FILENAME_H__
</pre></td></tr></table></P><P>
<LI>
<EM>Include `<TT>cssysdef.h</TT>'</EM>
<P>
Always include `<TT>cssysdef.h</TT>' in each source file as the very first file
included. If you need to use special facilities provided by `<TT>cssysdef.h</TT>'
then be sure to <CODE>#define</CODE> the appropriate macro before including
`<TT>cssysdef.h</TT>'.
</P><P>
<EM>Never</EM> include `<TT>cssysdef.h</TT>' in header files.
</P><P>
<LI>
<EM>Module and Library Dependencies</EM>
<P>
Do not introduce unnecessary dependencies between libaries and modules.
Absolutely avoid introducing circular dependencies.
</P><P>
For instance, code in the <CODE>csGeom</CODE> library should never refer to code
from the <CODE>csEngine</CODE> library. The other way around is okay, however,
since <CODE>csEngine</CODE> is at a higher level within the dependency hierarchy.
</OL>
<A NAME="CVS Guide"></A>
<HR SIZE=1>
<TABLE CELLPADDING=1 CELLSPACING=1 BORDER=0>
<TR><TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_273.html#SEC644"> < </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_275.html#SEC646"> > </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_271.html#SEC637"> << </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_271.html#SEC637"> Up </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_277.html#SEC648"> >> </A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT"> <TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="index.html#SEC_Top">Top</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_toc.html#SEC_Contents">Contents</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_285.html#SEC711">Index</A>]</TD>
<TD VALIGN="MIDDLE" ALIGN="LEFT">[<A HREF="cs_abt.html#SEC_About"> ? </A>]</TD>
</TR></TABLE>
<BR>
<FONT SIZE="-1">
This document was generated
using <A HREF="http://www.mathematik.uni-kl.de/~obachman/Texi2html
"><I>texi2html</I></A>
</BODY>
</HTML>
|
