Preface

This document is part of the LiveSupport project, Copyright © 2004 Media Development Loan Fund, under the GNU GPL.

Scope

This document describes C++ header file conventions for the LiveSupport project. See also the generic description of the file conventions in the LiveSupport project.

Introduction

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 #include in multiple source files. They are text based files, thus they should adhere to the generic text-based conventions.

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.

Naming

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 Foo and FooBar.

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 .h extension. Thus a class named Foo is defined in the header file Foo.h, and the class named SomeOtherLongNamedClass is defined in the header file named SomeOtherLongNamedClass.h.

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.

The file has the following mandatory structure:

Header

The header holds all information mandated by the generic guidelines. It begins with the generic header information, enclosed in 80 column wide partitioning delimiters.

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:
#include "Foo.h"
the identity macro is defined as Foo_h. For a header file that is expected to be included as:
#include "LiveSupport/Foo/Bar.h"
the identity macro is defined as LiveSupport_Foo_Bar_h.

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).

Sample

A sample for a C++ header file header follows, where the file itself would be expected to be included as "LiveSupport/Foo/Bar.h".

/*------------------------------------------------------------------------------

Copyright (c) 2004 Media Development Loan Fund

This file is part of the LiveSupport project.
http://livesupport.campware.org/
To report bugs, send an e-mail to bugs@campware.org

LiveSupport 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.

LiveSupport 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 LiveSupport; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA


Author : $Author: maroy $
Version : $Revision: 1.2 $
Location : $Source: /home/paul/cvs2svn-livesupport/newcvsrepo/livesupport/doc/developmentEnvironment/cxxHeaderFileConventions.html,v $

------------------------------------------------------------------------------*/
#ifndef LiveSupport_Foo_Bar_h
#define LiveSupport_Foo_Bar_h

#ifndef __cplusplus
#error This is a C++ include file
#endif

Include files & namespace

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.

After the includes, namespace definitions follow. Each LiveSupport object is contained in its own namespace inside the LiveSupport namespace, thus this is a nested namespace declaration.

After the namespace declarations, the namespaces used within the include file itself are listed with using namespace clauses. Note that the using namespace clauses are strictly within the namespace declaration clauses, so that they only take effect within the header file, but not afterwards.

Sample

A sample include files & namespaces section follows.
/* =============================================== include files & namespaces */

#ifdef HAVE_CONFIG_H
#include "configure.h"
#endif

#if HAVE_STDLIB_H
#include <stdlib.h>
#else
#error need stdlib.h
#endif

#include <string>


namespace LiveSupport {
namespace Foo {

using namespace LiveSupport::Core;

Constants

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,

Sample

A sample constants section follows.
/* ================================================================ constants */

/**
* The contant value of foo bar.
*/
static const int fooBarConst;

Macros

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,

Sample

A sample macros section follows.
/* =================================================================== macros */

/**
* Some very important macro.
*/
#define SOME_MACRO "some macro"

Data types

This section contains the data type definitions of the header file, most notable the definition of the class this header file is named after.

The class itself and all its members (including private members) are described by doxygen comments. The Java style of commenting is to be used.  For the comment describing the entire class, the @author and @version tags are mandatory. For each member function, all parameters, the return value and all possibly thrown exceptions are to be documented.

The class lists its members in the following order:
Within each of the above blocks, the order is the following:
For proper indentation of the above blocks, see the example below.

Sample

A sample data types section follows.
/* =============================================================== data types */

/**
* Hello class.
* The only purpose of this class is to say hello.
*
* @author $Author: maroy $
* @version $Revision: 1.2 $
*/
class Hello
{
private:
/**
* Our famous hello string.
*/
static const std::string helloWorld;

public:
/**
* Default constructor.
*/
Hello (void) throw ()
{
}

/**
* Say hello.
*
* @return the string "Hello, World!"
* @exception std::exception on problems
*/
const std::string
hello (void) throw (std::exception)
{
return helloWorld;
}
};

External data structures

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.

Sample

A sample external data structures section follows.
/* ================================================= external data structures */

/**
* An externally defined data, which the linker will find.
*/
extern int fooBarInt;

Function prototypes

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.

Sample

A sample function prototypes section follows.
/* ====================================================== function prototypes */

/**
* An important foo function.
*
* @return the result of foo.
*/
int foo(void) throw ();

Footer

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.

Sample

A sample footer section follows.

} // namespace Foo
} // namespace LiveSupport

#endif // LiveSupport_Foo_Bar_h

Template

See a template C++ header file. You may freely copy this template when starting to create a new header file.