Style Guide¶
Code Style¶
This project follows Google's C++ Style Guide with the following amendments:
camelCase
should be used for function names
ALL_CAPS
should be used for constants (in addition to macros)
If a class/function could feasibly be upstreamed to MFEM or implements an MFEM interface, it should
be part of the serac::mfem_ext
namespace and use MFEM's PascalCase
naming convention.
The Google style guide is meant for style enforcement only. The design principles outlined in the C++ Core Guidelines should be followed.
Of particular importance are the guidelines proposed for managing object lifetime:
Use raw pointers and references [only] to denote non-ownership (R.3 - R.4)
Prefer
unique_ptr
toshared_ptr
(R.21)
For example, if an object A
creates a subobject B
whose constructor requires a reference
to one of A
's instance variables Foo f
, B
should store a non-owning reference to f
,
either Foo&
or Foo*
. This should be const
if at all possible. In this case, shared ownership
is not required because the lifetime of B
is entirely dependent on the lifetime of A
.
Documentation¶
Functions, structs, classes, and critical member variables should be annotated with Doxygen comments. These comments should be enclosed in Javadoc-style comment blocks. For example, a variable can be documented as follows:
/**
* The MPI communicator
*/
MPI_Comm m_comm;
When annotating code, especially functions, Doxygen's special commands can come in handy to provide additional information:
/**
* Calculate du_dt = M^-1 (-Ku + f).
* This is all that is needed for explicit methods
* @param[in] u The state vector (input to the differentiation)
* @param[out] du The derivative of @p u with respect to time
* @see https://mfem.github.io/doxygen/html/classmfem_1_1TimeDependentOperator.html
*/
virtual void Mult(const mfem::Vector &u, mfem::Vector &du_dt) const;
For non-void
functions, the @return
command should be used to describe the return value.