3.4 Comment layout

• Comments MUST be written in English.
• You SHOULD prefer C-style (/** ... */) comments for long comments and C++/C99-style (/// ...) comments for one-line comments.
• You MUST NOT document the obvious.

  Don't write:

            /// Declaration of the Foo class.
            class Foo
            {
              ...
            };
       

  It is so obvious that you're documenting the class and the constructor that you should not write it down. Instead of documenting the kind of an entity (class, function, namespace, destructor...), document its goal.

• You SHOULD use the imperative when documenting, as if you were giving order to the function or entity you are describing. When describing a function, there is no need to repeat “function” in the documentation; the same applies obviously to any syntactic category. For instance, instead of:

            /// \brief Swap the reference with another.
            /// The method swaps the two references and returns the first.
            ref& swap (ref& other);
       

  write:

            /// @brief Swap the reference with another.
            /// Swap the two references and return the first.
            ref& swap (ref& other);
       

  The same rules apply to ChangeLogs.

• You SHOULD write your documentation in Doxygen.
• You MUST document your extern functions, your class and their methods, in the header that declares them, not in the file that implement them.

  Rationale: The clients of your interfaces will read your headers to know how your library or module works. They don't want to dig in the implementation to find the documentation.

  Rationale: The code is much more read that written and you should favor the (many) readers instead of the (often only) implementer.

  Rationale: Doing so leaves you some room to comment your implementation.