<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html401/loose.dtd">
<html>
<!-- Created by texi2html 1.76 -->
<!--
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: Many creative people <dev@texi2html.cvshome.org>
Send bugs and suggestions to <users@texi2html.cvshome.org>
-->
<head>
<title>Crystal Space 1.2.1: 7.3 Coding Style</title>
<meta name="description" content="Crystal Space 1.2.1: 7.3 Coding Style">
<meta name="keywords" content="Crystal Space 1.2.1: 7.3 Coding Style">
<meta name="resource-type" content="document">
<meta name="distribution" content="global">
<meta name="Generator" content="texi2html 1.76">
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
<style type="text/css">
<!--
a.summary-letter {text-decoration: none}
pre.display {font-family: serif}
pre.format {font-family: serif}
pre.menu-comment {font-family: serif}
pre.menu-preformatted {font-family: serif}
pre.smalldisplay {font-family: serif; font-size: smaller}
pre.smallexample {font-size: smaller}
pre.smallformat {font-family: serif; font-size: smaller}
pre.smalllisp {font-size: smaller}
span.sansserif {font-family:sans-serif; font-weight:normal;}
ul.toc {list-style: none}
-->
</style>
</head>
<body lang="en" bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#800080" alink="#FF0000">
<a name="Coding-Style"></a>
<a name="0"></a>
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Portability.html#0" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="SVN-Guide.html#0" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="Contributing.html#0" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="Contributing.html#0" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Glossary.html#0" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="cs_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="cs_Index.html#0" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="cs_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<hr size="1">
<h2 class="section"> 7.3 Coding Style </h2>
<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="Portability.html#0">Portability</a>.
</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>
<table><tr><td> </td><td><pre class="example">void foo()
{
int a;
for (a = 0; a < 10; a++)
{
int b = bar();
if (a < b)
printf ("Hello\n");
}
}
</pre></td></tr></table>
<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>In cases you are unsure what specific coding style to employ, just follow the
style in the code you're editing or your personal preference. Always try to
keep it both readable and consistent.
</p>
</li><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 (also known
as "CamelCase").
</p>
<p>Methods and functions should be named in this fashion: <code>ThisIsAMethod()</code>.
Each word in the name is capitalized.
</p>
</li><li>
<em><small>SCF</small> Interfaces</em>
<p><small>SCF</small> interfaces always start with a lower <samp>‘i’</samp>, as in
<code>iThisIsAnInterface</code>. See section <a href="SCF.html#0">Shared Class Facility (<small>SCF</small>)</a>.
</p>
</li><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 <small>HTML</small>
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>However, it is not required to document (re)implementations of methods (such
as for implementations of the virtual abstract methods of interfaces) since
Doxygen will automatically copy the documentation from the superclass.
Additionally, in practice, the documentation for the subclass is often only
copied from the superclass anyway, and most likely those two will get out of
sync over time; hence, save the effort of copying the Doxygen documentation
for a subclass, as the inherited documentation will likely also be more
accurate in the long run. Obvious exceptions are when a subclass method has
significant or important differences in functionality to the superclass method.
In this case, investigate Doxygen commands such as <samp>‘\copydoc’</samp>.
</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 class="dots">...</small> */’</samp> rather than <samp>‘/* <small class="dots">...</small> */’</samp>. Here is an
example:
</p>
<table><tr><td> </td><td><pre class="example">/// Namespace for potentially bouncy classes.
namespace Bouncy
{
/**\file
* This is an include file.
* Put a \\file block in headers so macros and global symbols get documented.
*/
/// Ball states
enum
{
/// Ball is limpy
Limpy,
/// Ball is floppy
Floppy
};
/**
* This class represents a blue ball.
* Blue balls bounce higher than red balls.
*/
class csBlueBall
{
private:
/**
* A private function - does not show up in the public documentation, but
* but still commented for readers of the header file or the developer
* documentation.
*/
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.
* \param speed How fast the ball is to be deflated.
* <i>Document parameters that way.</i>
* \return State of the ball - #Limpy or #Floppy.
* <i>Document return parameters that way. Also shows how to refer to enum
* entries.</i>
*/
int Deflate(int speed);
};
} // namespace Bouncy
</pre></td></tr></table>
</li><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>
</li><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>
<table><tr><td> </td><td><pre class="example">#ifndef __CS_FILENAME_H__
#define __CS_FILENAME_H__
...
#endif // __CS_FILENAME_H__
</pre></td></tr></table>
</li><li>
<em>Include <tt>‘cssysdef.h’</tt></em>
<p>Always include <tt>‘cssysdef.h’</tt> in each source or header file as the very
first file included. The latter is recommended, as it makes headers more
self-contained.
</p>
</li><li>
<em>Module and Facility Dependencies</em>
<p>Although most facilities from <tt>‘CS/libs’</tt> end up in the same link library
(<tt>‘crystalspace.lib’</tt>), you should not introduce unnecessary dependencies
between these facilities. There are clean lines between the various libraries
and their levels of generality or specialization which we prefer to maintain.
Absolutely avoid introducing circular dependencies.
</p>
<p>For instance, code in the “csutil” module should never refer to code
from the “cstool” module. The other way around is okay, however,
since “cstool” is at a higher level within the dependency hierarchy than
“csutil”.
</p></li></ol>
<hr size="1">
<table cellpadding="1" cellspacing="1" border="0">
<tr><td valign="middle" align="left">[<a href="Portability.html#0" title="Previous section in reading order"> < </a>]</td>
<td valign="middle" align="left">[<a href="SVN-Guide.html#0" title="Next section in reading order"> > </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="Contributing.html#0" title="Beginning of this chapter or previous chapter"> << </a>]</td>
<td valign="middle" align="left">[<a href="Contributing.html#0" title="Up section"> Up </a>]</td>
<td valign="middle" align="left">[<a href="Glossary.html#0" title="Next chapter"> >> </a>]</td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left"> </td>
<td valign="middle" align="left">[<a href="index.html#SEC_Top" title="Cover (top) of document">Top</a>]</td>
<td valign="middle" align="left">[<a href="cs_toc.html#SEC_Contents" title="Table of contents">Contents</a>]</td>
<td valign="middle" align="left">[<a href="cs_Index.html#0" title="Index">Index</a>]</td>
<td valign="middle" align="left">[<a href="cs_abt.html#SEC_About" title="About (help)"> ? </a>]</td>
</tr></table>
<p>
<font size="-1">
This document was generated using <a href="http://texi2html.cvshome.org/"><em>texi2html 1.76</em></a>.
</font>
<br>
</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
bad97183153701b09df5fae1052b1c30
>
files
>
4130
