This document describes C++ source file conventions for the
Campcaster
project. See also the generic description of the file
conventions in the Campcaster
project.
Introduction
C++ source files are files containing implementations of functions and
definitions of static data. They are text
based files, thus they should adhere to the generic text-based
conventions.
The Campcaster project uses a strong object oriented approach. Part of
this approach is to group implementations of classes into their own
files: one header file and one source file for each class. Therefore
each C++ source file contains implementation of exactly one C++ class,
although static (local) functions may be defined as well.
Naming
A C++ source files name reflects the class it is implementing. 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 Foo and FooBar.
As the name of the source file reflects the name of the class it
implements, the source file will be named exactly as the class inside,
with the .cxx extension. Thus a class named Foo
is implemented in the source file Foo.cxx, and the class
named SomeOtherLongNamedClass is implemented in the
source file named SomeOtherLongNamedClass.cxx.
Structure
C++ files are partitioned by using the following 80 column wide
partitioning comment:
/* ==================================================== name of the partition */
Note that the comment is always 80 columns wide, independent of the
length of the text within.
Local data type definitions and function prototypes required
doxygen-style commenting.
Function implementations and static data definitions were already
commented for doxygen at their place of declaration. Therefore these
are preceded by the following simple comment header.
/*------------------------------------------------------------------------------ * Function implementation below. *----------------------------------------------------------------------------*/
The file has the
following mandatory structure:
Header
Include files & namespaces
Local data structures
Local constants & macros
Local function prototypes
Module code
Header
The header holds all information mandated by the generic guidelines. It contains
with the generic header information, enclosed in 80
column wide partitioning delimiters.
This file is part of the Campcaster project. https://www.campware.org/ To report bugs, send an e-mail to [email protected]
Campcaster is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.
Campcaster is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with Campcaster; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
Author : $Author: paul $ Version : $Revision: 2373 $ Location : $URL: svn://code.campware.org/campcaster/trunk/campcaster/doc/developmentEnvironment/cxxSourceFileConventions.html $
This section contains all the include files that the source file needs
to include, plus namespace references. The include files are listed in
a most generic to most specific order: first system include files, then
other Campcaster module include files, and finally include files from
the same module / product are listed. The last one is the header file
for the class this source file implements.
After the includes, the namespaces used within the source file itself
are listed with using namespace clauses. The order of the
using namespace declarations is also from most generic to
most specific, the last one being the namespace of the class this
source file implements.
Sample
A sample include files & namespaces section follows.
/* =============================================== include files & namespaces */
#if HAVE_STDLIB_H #include <stdlib.h> #else #error need stdlib.h #endif
#include <string>
#include <Campcaster/Foo/Bar.h>
using namespace Campcaster::Core; using namespace Campcaster::Foo;
Local data structures
The constants section contains locally defined data structures, that
are not used anywhere outside this source file.
Nowhere in the source file may be other data structure definitions.
This section is
rarely used, as reusable data structures are encouraged.
Sample
A sample local data structures section follows.
/* =================================================== local data structures */
/** * The union of foo. */ union foo { int foo; long bar; };
Local constants & macros
The local constants & macros section contains any macros and
constant values used in this source file. It also contains the
definitions for constant values of the class this source file
implements. Nowhere in the source file may be other macros or constants
defined.
Having local constants is discouraged. Have private static class
members instead.
Sample
A sample local constants & macros section follows.
/* ================================================ local constants & macros */
/*------------------------------------------------------------------------------ * The famous foo string for the class Bar. *----------------------------------------------------------------------------*/ const std::string Bar::fooStr = "foo";
Local function prototypes
This section contains the prototypes for local functions, which are
only used in this source file. Nowhere else in the source file may
function prototypes be other than in this section. This section is
rarely used, local functions are discouraged. Use private class member
functions instead.
Sample
A sample local function prototypes section follows.
/* =============================================== local function prototypes */
/** * Some local function. * * @param parameter some parameter * @return a very big return value. */ int localFunction(int parameter) throw ();
Module code
This section contains the implementation for the class it is made for.
Also contains the implementation for all local functions. The
implementation order is not defined.
/*------------------------------------------------------------------------------ * Return the famous bar string. *----------------------------------------------------------------------------*/ const std::string Bar :: sayBar(void) throw (std::exception) { if (barInt) { throw std::exception(); }
return barStr; }
Template
See a template
C++ source file. You may freely copy this
template when starting to create a new source file.