This document describes the coding style for the TUVision Image Library.

Contents:

  1. Headers for cpp and h-files
  2. Class declaration conventions
  3. Semantic documentation
  4. Class declaration conventions
  5. Enum declaration conventions
  6. Fuction typedef declaration conventions
  7. Template class declaration conventions
  8. Implementation file and commenting conventions
  9. Implementation detail conventions

Headers for cpp and h-files:

All files always have the following header:
/***************************************************************************
                          FILE.CPP/FILE.H  -  description
                             -------------------
    begin                : DATE
    copyright            : (C) YEAR by AUTHOR
    email                : tuvisionlib@tuvision.de
    origin               : IN WHICH PROJECT THIS FILE HAS BEEN CREATED

 ***************************************************************************/

/***************************************************************************
 *                                                                         *
 *   This file is part of the TUVision Library. It is free software; you   *
 *   can redistribute it and/or modify it under the terms of the           *
 *   GNU Library General Public License as published by the Free Software  *
 *   Foundation; either version 2 of the License, or (at your option)      *
 *   any later version.                                                    *
 *                                                                         *
 ***************************************************************************/
All H - files have to have a ".h" - suffix.

Class declarations:

Class declarations are prefixed with a 'C'.

Comments are in "Qt" style.

The header files contain only short descriptions. The class is structured as follows:

first the methods,
sorted by public, protected and lastly private access,
finally the variables,
sorted by public, protected and lastly private access.
The member variables have a leading "d_" and are all lowercase, words separated by underscores.
The member functions are always separated by an empty line.

The implementation files contain the full descriptions of the menmber functions. The member variables are briefly commented in the header file (see below).

Each class description (e.g. the one shown below) in the .h - file has to have a \class - line in which the tuv - subdirectory is mentioned. Example: File tuv/CImageByteGray.h has to have the following documentation for the class CImageByteGray:

/*! ...
 *  ...
 * \class CImageByteGray CImageByteGray.h tuv/CImageByteGray.h

Comments are required for every member variables and function before initial cvs checkin.

/**********************************************************/
//!  One line brief description. 
/*! 
 *   More descriptive text.
 *
 *   \author name  
 *   \author name 
 *   
 *   (optional:)
 *   \code 
 *      short example code;
 *   \endcode 
 *
 *   \example example-code-filename
 *   
 *   \warning warning-description, exceptional behaviour
 *   \warning warning-description, exceptional behaviour
 *   
 *   \bug known-bug
 *   \bug known-bug
 * \class CLASSNAME HEADERFILE.H TUV_INCLUDEDIRECTORY/HEADERFILE.H
 */
/**********************************************************/

class CClass : public CBaseClass { 

  public:
    // CREATORS 

    CClass(); 
    virtual ~CClass(); 

    // MANIPULATORS 

    /******************************************************/
    //!  One line brief description. 
    /******************************************************/
    void setSomething ( setType type_name);

    // ACCESSORS 

    /******************************************************/
    //!  One line brief description. 
    /******************************************************/
    return_type getSomething();

  protected: 
    // MANIPULATORS 
    ... 
    // ACCESSORS 
    ... 
  private: 
    // MANIPULATORS 
    ... 
    // ACCESSORS 
    ... 
  public:  
    ... 
    static const int CONSTANT=0;  // constants are all UPPERCASE
    ... 
    float d_float;  //member are prefixed with d_ 
    ... 
  protected: 
    double d_double; //!< member variable comment

  private: 
    const string& d_string; 
}; 
      

Semantic documentation begin in h-file (below all code):

/*! \page ClassName Name of Page 
 *     -  \ref CFilterNoiseReductionsyntactic
 *			
 *
 * 		\section CFilterNoiseRedUMexpic example picture
 *			
 *			\image html CFilterNoiseRedution2.jpg "Vorher -> Nachher"				
 *			\image latex CFilterNoiseRedution2.jpg "Vorher -> Nachher"			
 *																	(delete these lines)
 *		\section CFilterNoiseRedUMbe Brief explanation
 *			...
 *
 *		\section CFilterNoiseRedUMde Detailled explanation
 *			...
 *
 *		  \subsection CFilterNoiseRedUMlpf Low pass filter
 *			...
 *	 	  \subsection CFilterNoiseRedUMnt Next topic
 *		    ...
 *
 *		\section CFilterNoiseRedUMconcl Conclusion
 *			...
 */


THE FOLLOWING IS TO ADD TO THE DETAILED DESCRIPTION:

/*! \anchor CFilterNoiseReductionUMsyntactic
 *	\ref CFilterNoiseReductionUMsemantic semantic Declaration
 *
 *  ... detailed decription
 */  

IMAGE-PATH: tuvisionlib\docs\images
(here your pictures should be placed)

FORMATION:
the structure of the semantic documantation:
1. example picture
2. short explanation
3. detailed explanation (subdivided into topics as section)
4. summary (i.e. as diagram)
5. pros and cons

Struct declarations are prefixed with a 'S':

struct SStruct { 
}; 

Enum declarations are prefixed with an 'E':

  enum EEnum { 
  }; 

Function typedef declarations are prefixed with a 'L':


  typedef void (*LProc)(); 

Template classes are handled like normal classes:

  template 
  class CTemplateClass {
    ...
  };

Implementation file conventions:

C++ Implementation files always have the ending ".cpp"

C++ method naming and commenting convention:

/**********************************************************/
/*! 
 *   More descriptive text.
 *
 *   \param param_name param-description
 *   \param param_name param-description
 *   \return return-description
 *
 *   \author name
 */
/**********************************************************/

ReturnType 
CClass::functionName(ParamType param_name, ...) 
{ 
} 

C function naming convention:

The only place to put C functions into are ".c" files. These functions should not be visible to the user of the C++ class and therefore encapsulated by forward declaring the signatures of the C functions in the C++ implementation file.
ReturnType 
name_of_c_function (ParamType param_name, ...) 
{ 
}
Do not forget to include the
extern "C" {

  ReturnType name_of_c_function ( ... );

}
in the ".cpp" C++ implementation file.

Implementation detail definitions:

if statements:

The else statement belongs into the next line.
    if (...) { 
        ... 
    } 
    else { 
      ... 
    } 

    if (...) { 
      ... 
    } 
    else if (...) { 
      ... 
    } 
    else if (...) { 
      ... 
    } 
    else { 
      ... 
    } 

switch statements:

The case statement belongs into the next line. Each case block is encapsulated by curly brackets (i.e. form an own statement list).
Each case block is ended with break. A case block "fallthrough" is an exception and should be noted in the comments at the beginning of the block.
    switch (...) { 
      case ...: 
        { 
          ... 
        } 
        break; 
      case ...: 
        { 
          ... 
        } 
        break; 
      // EXCEPTION: this case falls through.
      case ...: 
        {
          ... 
        } 
      case ...: 
        { 
          ... 
        } 
        break; 
      default: 
        { 
           ... 
        } 
        break; 
    }