CodingConventions

Coding conventions

This page describes, how charon code should look like. Especially if you write new plugins and want them to be integrated into the charon plugin collections, please read this document carefully.

CamelCase

Avoid using variables containing underscores (e.g. my_bad_variable) but use CamelCase versions (like myCoolVariable).

C++

Name conventions

• Class names start with a capital letter
  (e.g. class Crop)
• Variable and object names start with a lowercase letter
  (e.g. int i)
• Private and protected members start with a underscore
  (e.g. std::string _name)

Comments and Documentation

We use [http://www.doxygen.org/ Doxygen] for documentation creation.
For information how to document your classes, functions etc. see its [http://www.doxygen.org/manual.html Manual].

• Each file, class and function should be documented using
  Doxygen comment strings. Look at doxygens output to find out which
  documentation is still missing
• All doxygen documentation strings have to be located in the
  *.h file
• *.hxx/*.hpp and *.cpp files won't be parsed,
  but you should add at least the /** \file ... */ comments as header
• Doxygen comments should use the Qt style, i.e. the first brief
  description starts with ///, the detailed description is located
  in a /** ... */ block

File separation

We want to separate interfaces from their implementation. Therefore, there is usually at least a *.h and a *.cpp file.
Templated functions cannot be implemented in the *.cpp file, therefore we additionally need a *.hxx or *.hpp file.

• Class declaration and function prototypes go to the *.h file. No implementation there!
• Implementation of template function goes to the *.hxx or *.hpp file.
• Implementation of non-templated functions goes to the *.cpp file.

Indentation

• Use TAB for indentation at line beginnings, but no TABs later
• private:, protected: and public: should not be indented.
• Avoid lines with more than 80 characters.

A class interface MyClass.h should look like this:

//  Copyright header (LGPL)

/** \file MyClass.h
 *  Declaration of class MyClass
 *  \author <a href="mailto:me@mail.org">me</a>
 *  \date 2010-01-19
 */

/// short class description
/** optional
 *  long class description
 */
class MyClass {
private:
    /// some private function
    void _privateFunction();

public:
    /// public constructor
    /** \param[in] name    object name
     */
    MyClass(const std::string& name);

    /// some public function
    void publicFunction(int i /**[in] some integer input*/);
};

The implementation in MyClass.cpp could look as follows:

//  Copyright header (LGPL)

/// \file MyClass.cpp
/** Implementation of class MyClass
 *  \author <a href="mailto:me@mail.org">me</a>
 *  \date 2010-01-19
 */

void MyClass::_privateFunction() {
    // some code
}

MyClass::MyClass(const std::string& /*name*/) {
    // please comment out unused parameters
    // to show, that you did not simply forget them

    // some more code
}

void MyClass::publicFunction(int i) {
    if (i == 0) {
        // do something
    }
}

CMake

Option naming

Using the following conventions makes option grouping in the grouped
view of cmake-gui easier and simplifies writing gentoo ebuilds a lot
(there are some automatic functions to enable or disable
options starting with the prefixes mentioned below).

• CMake options which allow integration of some external libraries
  (e.g. lapack, png, ...)
  should start with USE_... (e.g. USE_LAPACK)
• CMake options which allow enabling or disabling some features
  (like compilation of some more plugins) should begin with BUILD_...
  (e.g. BUILD_SOLVERS)