Coding Style

Table of Contents

• Naming
• Files
• Documentation

The following Coding Style is recommended for ug.

---

Naming

• Global Functions are named using Camel Case, i.e. each element's initial is letter capitalized.

  int AddTwoIntegers(int a, int b);

• Classes are named using Camel Case, i.e. each element's initial is letter capitalized. The members of a class should be named like this:
  • member variables are indicated by an leading m_ followed by a lower camel case style
  • pointer member variables are indicated by an leading m_p
  • member functions (methods) are named in lower case separating each word by an underscore _

  class MyClassOfTwoIntegers
  {
    {}
   
    int& get_first_integer() {return m_firstInteger;}
    int& get_second_integer() {return *m_pSecondInteger;}
          
    private:
      int m_firstInteger;
      int* m_pSecondInteger;
  };

• Interface Classes should be named by an leading capital I

  class IVehicle
  {
    public:
      virtual void drive() = 0;
  };

• Template parameters should be indicated by an leading capital T

  template <typename TDomain, typename TMatrix>
  void AssembleMatrixOnDomain(TDomain& dom, TMatrix& mat);

---

Files

Files are named by using lower case letters and separating each word by an underscore _. Please try to separate declaration and definition (implementation) into separate files:

• *.h — files contain the declaration of functions and classes
• *_impl.h — files contain the implementation of inline and template functions/classes
• *.cpp — files contain the rest of the implementation

Example:

• domain_util.h

  #ifndef __H__UG__LIB_DISC__DOMAIN_UTIL__
  #define __H__UG__LIB_DISC__DOMAIN_UTIL__
   
  namespace ug{
   
  // ... declaration of classes and functions ...
   
  } // end namespace ug
   
  // include implementation
  #include "./domain_util_impl.h"
   
  #endif /* __H__UG__LIB_DISC__DOMAIN_UTIL__ */

• domain_util_impl.h

  #ifndef __H__UG__LIB_DISC__DOMAIN_UTIL_IMPL__
  #define __H__UG__LIB_DISC__DOMAIN_UTIL_IMPL__
   
  // include declarations
  #include "./domain_util.h"
   
  namespace ug{
   
  // ... implementation of inline and template classes/functions ...
   
  } // end namespace ug
   
  #endif /* __H__UG__LIB_DISC__DOMAIN_UTIL_IMPL__ */

• domain_util.cpp

  // include declarations
  #include "./domain_util.h"
   
  namespace ug{
   
  // ... implementation ...
   
  } // end namespace ug

---

Documentation

In ug4 Doxygen is used to document the code (see http://www.doxygen.org). The JavaDoc style is the preferred documentation style.

Documentation of functions should be placed at their declaration not implementation respectively defintion (if split up into different files).

See the Doxygen Quick Reference for the most important commands and how to use them.

/**
 * \brief A brief documentation
 *
 * A long description of the class.
 *
 * \tparam TParam The docu of the template Parameter
 */
template <typename TParam>
class SomeClass
{
  public:
    /**
      * \brief short docu of member function
      *
      * long docu of the member function
      *
      * \param[out] firstParam  docu of outgoing parameter
      * \param[in]  secondParam docu of ingoing parameter
      * \return \c true docu of return value  
      */
    bool some_member_function(int& firstParam, const int secondParam);
}