202 lines
12 KiB
HTML
202 lines
12 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<html>
|
|
<head>
|
|
<meta content="text/html; charset=UTF-8" http-equiv="content-type">
|
|
<title>C++ header file conventions</title>
|
|
<meta content="$Author: maroy $" name="author">
|
|
</head>
|
|
<body>
|
|
<h1>Preface</h1>
|
|
This document is part of the <a href="http://livesupport.campware.org/">LiveSupport</a>
|
|
project, Copyright © 2004 <a href="http://www.mdlf.org/">Media
|
|
Development Loan Fund</a>, under the GNU <a
|
|
href="http://www.gnu.org/licenses/gpl.html">GPL</a>.<br>
|
|
<ul>
|
|
<li>Author: $Author: maroy $</li>
|
|
<li>Version: $Revision: 1.2 $</li>
|
|
<li>Location: $Source:
|
|
/home/cvs/livesupport/doc/developmentEnvironment/cxxHeaderFileConventions.html,v
|
|
$</li>
|
|
</ul>
|
|
<h1>Scope</h1>
|
|
This document describes C++ header file conventions for the
|
|
LiveSupport
|
|
project. See also the generic description of the <a
|
|
href="fileConventions.html">file
|
|
conventions</a> in the LiveSupport
|
|
project.<br>
|
|
<h1>Introduction</h1>
|
|
C++ header files are files containing declarations of structures,
|
|
functions and classes, that may be shared among object files, by
|
|
including them with the pre-processor directive <code>#include</code>
|
|
in multiple source files. They are text
|
|
based files, thus they should adhere to the <a
|
|
href="fileConventions.html#textConventions">generic text-based
|
|
conventions</a>.<br>
|
|
<br>
|
|
The LiveSupport project uses a strong object oriented approach. Part of
|
|
this approach is to group declarations of classes into their own files:
|
|
one header file and one source file for each class. Therefore each C++
|
|
header file contains the declaration of exactly one C++ class, although
|
|
inner types are defined in the same file.<br>
|
|
<h1>Naming</h1>
|
|
A C++ header files name reflects the class it is defining. Class names
|
|
begin with a capital letter, followed by lower case letters. In case of
|
|
a multiple word class name, the first letter of each word is
|
|
capitalized. Example class names are <code>Foo</code> and <code>FooBar</code>.<br>
|
|
<br>
|
|
As the name of the header file reflects the name of the class defined
|
|
in it, the header file will be named exactly as the class inside, with
|
|
the <code>.h</code> extension. Thus a class named <code>Foo</code> is
|
|
defined in
|
|
the header file <code>Foo.h</code>, and the class named <code>SomeOtherLongNamedClass</code>
|
|
is defined in the header file named <code>SomeOtherLongNamedClass.h</code>.<br>
|
|
<h1>Structure</h1>
|
|
C++ files are partitioned by using the following 80 column wide
|
|
partitioning comment:<br>
|
|
<pre>/* ==================================================== name of the partition */<br></pre>
|
|
Note that the comment is always 80 columns wide, independent of the
|
|
length of the text within.<br>
|
|
<br>
|
|
The file has the
|
|
following mandatory structure:<br>
|
|
<ul>
|
|
<li>Header</li>
|
|
<li>Include files & namespaces</li>
|
|
<li>Constants</li>
|
|
<li>Macros</li>
|
|
<li>Data types</li>
|
|
<li>External data signatures</li>
|
|
<li>Function Prototypes</li>
|
|
<li>Footer<br>
|
|
</li>
|
|
</ul>
|
|
<h2>Header</h2>
|
|
The header holds all information mandated by the <a
|
|
href="fileConventions.html#header">generic guidelines</a>. It begins
|
|
with the generic header information, enclosed in 80
|
|
column wide partitioning delimiters.<br>
|
|
<br>
|
|
After this a macro definition follows, prohibiting the multiple time
|
|
inclusion of the header file. The name of the header-identity macro is
|
|
derived from the full name the file is expected to be included as. The
|
|
macro name is formed by replacing all non-alphanumeric characters from
|
|
the expected include definition with the '_' (underscore) character.
|
|
For a header file that will be included with the line:<br>
|
|
<pre><code>#include "Foo.h"</code><br></pre>
|
|
the identity macro is defined as <code>Foo_h</code>. For a header file
|
|
that is expected to be included as:<br>
|
|
<pre><code>#include "LiveSupport/Foo/Bar.h"<br></code></pre>
|
|
the identity macro is defined as <code>LiveSupport_Foo_Bar_h</code>.<br>
|
|
<br>
|
|
After the identity macro, a preprocessor check is performed to see if
|
|
the file is being processessed by a C++ compiler (and say not a C
|
|
compiler).<br>
|
|
<h3>Sample</h3>
|
|
A sample for a C++ header file header follows, where the file itself
|
|
would be expected to be included as <code>"LiveSupport/Foo/Bar.h"</code>.<br>
|
|
<br>
|
|
<pre>/*------------------------------------------------------------------------------<br><br> Copyright (c) 2004 Media Development Loan Fund<br> <br> This file is part of the LiveSupport project.<br> http://livesupport.campware.org/<br> To report bugs, send an e-mail to bugs@campware.org<br> <br> LiveSupport is free software; you can redistribute it and/or modify<br> it under the terms of the GNU General Public License as published by<br> the Free Software Foundation; either version 2 of the License, or<br> (at your option) any later version.<br> <br> LiveSupport is distributed in the hope that it will be useful,<br> but WITHOUT ANY WARRANTY; without even the implied warranty of<br> MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the<br> GNU General Public License for more details.<br> <br> You should have received a copy of the GNU General Public License<br> along with LiveSupport; if not, write to the Free Software<br> Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA<br> <br> <br> Author : $Author: maroy $<br> Version : $Revision: 1.2 $<br> Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/cxxHeaderFileConventions.html,v $<br> <br>------------------------------------------------------------------------------*/<br>#ifndef LiveSupport_Foo_Bar_h<br>#define LiveSupport_Foo_Bar_h<br> <br>#ifndef __cplusplus<br>#error This is a C++ include file<br>#endif<br><br></pre>
|
|
<h2>Include files & namespace <br>
|
|
</h2>
|
|
This section contains all the include files that the header file needs
|
|
to include, plus namespace declarations. The include files are listed
|
|
in a most generic to most specific order: firts system include files,
|
|
then other LiveSupport module include files, and finnally include files
|
|
from the same module / product are listed.<br>
|
|
<br>
|
|
After the includes, namespace definitions follow. Each LiveSupport
|
|
object is contained in its own namespace inside the <code>LiveSupport</code>
|
|
namespace, thus this is a nested namespace declaration.<br>
|
|
<br>
|
|
After the namespace declarations, the namespaces used within the
|
|
include file itself are listed with <code>using namespace</code>
|
|
clauses. Note that the <code>using namespace</code> clauses are
|
|
strictly within the namespace declaration clauses, so that they only
|
|
take effect within the header file, but not afterwards.<br>
|
|
<h3>Sample</h3>
|
|
A sample include files & namespaces section follows.<br>
|
|
<pre>/* =============================================== include files & namespaces */<br><br>#ifdef HAVE_CONFIG_H<br>#include "configure.h"<br>#endif<br><br>#if HAVE_STDLIB_H<br>#include <stdlib.h><br>#else<br>#error need stdlib.h<br>#endif<br><br>#include <string><br><br><br>namespace LiveSupport {<br>namespace Foo {<br><br>using namespace LiveSupport::Core;<br><br></pre>
|
|
<h2>Constants</h2>
|
|
The constants section contains static constant values defined in the
|
|
header file.
|
|
Nowhere in the header file may be other static constants defined. This
|
|
section is
|
|
rarely used, as static constants outside classes are discurraged,<br>
|
|
<h3>Sample</h3>
|
|
A sample constants section follows.<br>
|
|
<pre>/* ================================================================ constants */<br><br>/**<br> * The contant value of foo bar.<br> */<br>static const int fooBarConst;<br></pre>
|
|
<h2>Macros</h2>
|
|
The macros section contains any macros defined in the header file.
|
|
Nowhere in the header file may be other macros defined. This section is
|
|
rarely used, as macros are discurraged,<br>
|
|
<h3>Sample</h3>
|
|
A sample macros section follows.<br>
|
|
<pre>/* =================================================================== macros */<br><br>/**<br> * Some very important macro.<br> */<br>#define SOME_MACRO "some macro"<br></pre>
|
|
<h2>Data types</h2>
|
|
This section contains the data type definitions of the header file,
|
|
most notable the definition of the class this header file is named
|
|
after.<br>
|
|
<br>
|
|
The class itself and all its members (including private members) are
|
|
described by <a href="http://www.doxygen.org/">doxygen</a> comments.
|
|
The Java style of commenting is to be used. For the comment
|
|
describing the entire class, the <code>@author</code> and <code>@version</code>
|
|
tags are mandatory. For each member function, all parameters, the
|
|
return value and all possibly thrown exceptions are to be documented.<br>
|
|
<br>
|
|
The class lists its members in the following order:<br>
|
|
<ul>
|
|
<li>private</li>
|
|
<li>protected</li>
|
|
<li>public</li>
|
|
</ul>
|
|
Within each of the above blocks, the order is the following:<br>
|
|
<ul>
|
|
<li>static data members</li>
|
|
<li>dynamic data members</li>
|
|
<li>constructors</li>
|
|
<li>destructor</li>
|
|
<li>static functions</li>
|
|
<li>dynamic functions</li>
|
|
</ul>
|
|
For proper indentation of the above blocks, see the example below.<br>
|
|
<h3>Sample</h3>
|
|
A sample data types section follows.<br>
|
|
<pre>/* =============================================================== data types */<br><br>/**<br> * Hello class.<br> * The only purpose of this class is to say hello.<br> *<br> * @author $Author: maroy $<br> * @version $Revision: 1.2 $<br> */<br>class Hello<br>{<br> private:<br> /**<br> * Our famous hello string.<br> */<br> static const std::string helloWorld;<br><br> public:<br> /**<br> * Default constructor.<br> */<br> Hello (void) throw ()<br> {<br> }<br><br> /**<br> * Say hello.<br> *<br> * @return the string "Hello, World!"<br> * @exception std::exception on problems<br> */<br> const std::string<br> hello (void) throw (std::exception)<br> {<br> return helloWorld;<br> }<br>};<br><br></pre>
|
|
<h2>External data structures<br>
|
|
</h2>
|
|
The external data structures section contains any external data
|
|
definitions needed by the header file, that may be defined externally.
|
|
Nowhere in the header file may other external data definitions exist.
|
|
This section is
|
|
rarely used, as external data definitions are discouraged.<br>
|
|
<h3>Sample</h3>
|
|
A sample external data structures section follows.<br>
|
|
<pre>/* ================================================= external data structures */<br><br>/**<br> * An externally defined data, which the linker will find.<br> */<br>extern int fooBarInt;<br><br></pre>
|
|
<h2>Function prototypes<br>
|
|
</h2>
|
|
The function prototypes section contains any function prototypes
|
|
defined by the header file, that are not members of classes.
|
|
Nowhere in the header file may other such definitions exist.
|
|
This section is seldom used, as functions outside classes are
|
|
discouraged.<br>
|
|
<h3>Sample</h3>
|
|
A sample function prototypes section follows.<br>
|
|
<pre>/* ====================================================== function prototypes */<br><br>/**<br> * An important foo function.<br> *<br> * @return the result of foo.<br> */<br>int foo(void) throw ();<br></pre>
|
|
<h2>Footer</h2>
|
|
The footer of the header file closes the namespace brackets opened in
|
|
the include files & namespaces section, and also ends the header
|
|
identity macro #ifdef section opened in the header.<br>
|
|
<h3>Sample</h3>
|
|
A sample footer section follows.<br>
|
|
<br>
|
|
<pre>} // namespace Foo<br>} // namespace LiveSupport<br><br>#endif // LiveSupport_Foo_Bar_h<br></pre>
|
|
<h1>Template</h1>
|
|
See a <a href="templates/Bar.h">template
|
|
C++ header file</a>. You may freely copy this
|
|
template when starting to create a new header file.<br>
|
|
<br>
|
|
</body>
|
|
</html>
|