Programming Conventions
Imposing a standard usually is restrictive and annoying. But having a coding convention can help in understanding better and faster the code written by a team or even by only one programmer. The coding convection used in Kratos are described briefly in following sections.
Contents |
Classes
Class names must be in lower case except the first letter of each word in upper case as separator. For example:
class MyClassNameExample
Try to describe the type of the class with its name. Some typical cases are:
- Elements name must be finished with Element word:
class MyShellElement
- Conditions name must be finished with Condition word:
class My2DLoadCondition
- Linear solvers name must be finished with Solver word:
class GmresSolver
- Application classes must be started Kratos and finished with Application :
class KratosStructuralApplication
It can be seen that in all cases only the first letter of each word is in capital. It's important to mention that there is NO initial letter (like "C") to distinguish a class.
Class Members
Class members are in lower case with first letter of each word in capital starting with following prefixes:
- lower case m to indicate that they are member variables:
int mNumberOfElements;
- lower case mp to indicate that they are member pointers:
Node::Point mpFirstNode;
- lower case mr to indicate that they are member references:
Matrix& mrLocalMatrix;
Class Methods
Macros
Macros in Kratos are all uppercase with underline "_" as seperator and always starting with KRATOS_ as prefix:
#define KRATOS_AN_EXAMPLE_OF_MACRO
Arguments
Local Variables
Good Hints in programming
- avoid using raw pointers and C-arrays! C-arrays are EVIL!
- do not use the structure new/delete or even worst malloc/free. Do memory management via Boost::shared_ptr!
- do not reimplement linear algebra! use ublas instead!
- Use the Kratos data structures as much as possible! They will simplify your life!
- Use the const attribute as much as you can ... it will avoid many errors!
Doxygen
Commenting for classes consist of a brief description and a detailed one as follow:
/// Brief description. /** Detailed description. */
which must be placed just befor the class definition. for example in Geometry.h:
///Geometry base class.
/** As a base class Geometry has all the common
interface of Kratos' geometries. Also it contains array of
pointers to its points, reference to shape functions values in
all integrations points and also local gradients of shape
functions evaluated in all integrations points.
Geometry is a template class with just one template parameter:
- TPointType which reperesent the type of the point this geometry
type contain and build on.
\see Point
\see Node
\see Formulation
\see GeometryAndFormulationElement
*/
template<class TPointType>
class Geometry : public PointerVector<TPointType>
{
public:
....
}
It is very recommended to use the @see command which appears as see also with a link to indicate some related classes.
For methods of the class the same structure can be used but with information about parameters and return value if there is:
/** Jacobian in specific integration point of given integration
method. This method calculate jacobian matrix in given
integration point of given integration method.
\param IntegrationPointIndex index of integration point which jacobians has to
be calculated in it.
\param ThisMethod integration method which jacobians has to
be calculated in its integration points.
\return Matrix<double> Jacobian matrix \f$ J_i \f$ where \f$
i \f$ is the given integration point index of given
integration method.
\see DeterminantOfJacobian
\see InverseOfJacobian
*/
virtual Matrix& Jacobian(Matrix& rResult, IndexType IntegrationPointIndex, IntegrationMethod ThisMethod) const
{
....
}
The following commands can be used in documentation of methods and functions:
- \param to indicate a parameter of the method
- \return to indicate the return value of the method
- \see to include a see also
- \f$ \f$ Create a Latex formula in the document
- \f[ \f] for creating a centered latex formula
Here is an example:
/** Calculates center of this geometry by a simple averaging algorithm.
Each center point component calculated using:
\f[
c_i = \sum_j^n(x_i^j) / n
\f]
where \f$ c_i \f$ is component i of center point and \f$
X_i^j \f$ is component i of j'th point of geometry and n is
number of the points in this geometry.
@return PointType which is the calculated center of this geometry.
*/
virtual PointType Center() const
{
...
}
A quick reference to the doxygen commands can be found here
In kratos/kratos/template directory there is a header_template file prepared with grouping commands for class methods in Kratos.
