Coding Standards Comments

Comments

We are going to use Doxygen, so we follow that style of comments. The most important is a short descriptive text of the class/struct/attribute. Entries for parameters or a detailed description are recommended, especially when doing something complex.

• Functions & methods :

/**
 * \brief Returns a resource with the specified name.
 *
 * Bla bla bla bla bla bla bla ... (Optional detailed description)
 * \param[in] const std::vector<Property> &properties The creation properties for the resource.
 * \return bool True if initialization finished with no errors.
 */

or

/** \brief Remove and get a reference of an element
 * 
 * Bla bla bla bla bla bla bla ... (Optional detailed description)
 * \param key const K& the key of the element
 * \param element T& a non-const reference that will contain the element
 * \return bool true if removed, false otherwise
 */

or

/// \brief Remove and get a reference of an element
/**
 * Bla bla bla bla bla bla bla ... (Optional detailed description)
 * \param key const K& the key of the element
 * \param element T& a non-const reference that will contain the element
 * \return bool true if removed, false otherwise
 */

• For class attributes, constants, static vars, and global variables (ouch!) :

static const double PI = 3.14159265358979324; /// PI constant

static const double TAU = 2 * PI;  /// 2*PI constant

static bool UberFlag;     /// Uber important flag
                           /// (Optional detailed description) Indicates when we need to change the 
                           /// polarity of the neutron beam in the dilithium chamber.