/*
 * Copyright (c) 2010-2013:  G-CSC, Goethe University Frankfurt
 * Author: Andreas Vogel
 * 
 * This file is part of UG4.
 * 
 * UG4 is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License version 3 (as published by the
 * Free Software Foundation) with the following additional attribution
 * requirements (according to LGPL/GPL v3 §7):
 * 
 * (1) The following notice must be displayed in the Appropriate Legal Notices
 * of covered and combined works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (2) The following notice must be displayed at a prominent place in the
 * terminal output of covered works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (3) The following bibliography is recommended for citation and must be
 * preserved in all covered files:
 * "Reiter, S., Vogel, A., Heppner, I., Rupp, M., and Wittum, G. A massively
 *   parallel geometric multigrid solver on hierarchically distributed grids.
 *   Computing and visualization in science 16, 4 (2013), 151-164"
 * "Vogel, A., Reiter, S., Rupp, M., Nägel, A., and Wittum, G. UG4 -- a novel
 *   flexible software system for simulating pde based models on high performance
 *   computers. Computing and visualization in science 16, 4 (2013), 165-179"
 * 
 * This program 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 Lesser General Public License for more details.
 */

/** \page pageUG4CodingStyle Coding Style

[TOC]

The following Coding Style is recommended for ug.

<hr>
\section secCodingSyleNaming Naming

<ul>
  <li><strong>Global Functions</strong> are named using <em>Camel Case</em>, 
    i.e. each element's initial is letter capitalized.
    \code
    int AddTwoIntegers(int a, int b);
    \endcode
  </li>
  <li><strong>Classes</strong> are named using <em>Camel Case</em>, i.e. each 
    element's initial is letter capitalized.
    The members of a class should be named like this:
    <ul>
      <li><strong>member variables</strong> are indicated by an leading 
        <tt>m_</tt> followed by a lower camel case style
      </li>
      <li><strong>pointer member variables</strong> are indicated by an leading 
        <tt>m_p</tt>
      </li>
      <li><strong>member functions</strong> (methods) are named in lower case 
        separating each word by an underscore <tt>_</tt>
      </li>
    </ul>
    \code
class MyClassOfTwoIntegers
{
  {}

  int& get_first_integer() {return m_firstInteger;}
  int& get_second_integer() {return *m_pSecondInteger;}
        
  private:
    int m_firstInteger;
    int* m_pSecondInteger;
};
    \endcode
  </li>
  <li><strong>Interface Classes</strong> should be named by an leading capital 
    <tt>I</tt>
    \code
class IVehicle
{
  public:
    virtual void drive() = 0;
};
    \endcode
  </li>
  <li><strong>Template parameters</strong> should be indicated by an leading 
    capital <tt>T</tt>
    \code
template <typename TDomain, typename TMatrix>
void AssembleMatrixOnDomain(TDomain& dom, TMatrix& mat);
    \endcode
  </li>
</ul>


<hr>
\section secCodingSyleFiles Files

Files are named by using lower case letters and separating each word by an 
underscore <tt>_</tt>.
Please try to separate declaration and definition (implementation) into 
separate files:
<ul>
  <li><tt>*.h</tt> &mdash; files contain the declaration of functions and 
    classes
  </li>
  <li><tt>*_impl.h</tt> &mdash; files contain the implementation of inline and 
    template functions/classes
  </li>
  <li><tt>*.cpp</tt> &mdash; files contain the rest of the implementation</li>
</ul>

Example:
<ul>
  <li><tt>domain_util.h</tt>
    \code
#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__ */
    \endcode
  </li>
  <li><tt>domain_util_impl.h</tt>
    \code
#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__ */
    \endcode
  </li>
  <li><tt>domain_util.cpp</tt>
    \code
// include declarations
#include "./domain_util.h"

namespace ug{

// ... implementation ...

} // end namespace ug
    \endcode
  </li>
</ul>


<hr>
\section secCodingSyleDocumentation Documentation

In ug4 \em Doxygen is used to document the code (see http://www.doxygen.org).
The \em 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 \ref pageUG4DoxygenQuickref for the most important commands and how 
to use them.

\verbatim
/**
 * \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);
}
\endverbatim

*/
