C++ Style Guide Update

Following discussion on RFC-225 and its implementation tickets, the Documenting C++ Code section of the DM Style Guide has been reworked with more detailed guidelines that strike a compromise between the numpydoc-like convention we follow in Python, the capabilities of Doxygen, and differences between C++ and Python.

Major changes include:

  • Documentation comment style is standardized on /** or /// delimiters and tags like @param. /*! and \param are discouraged in new code.
  • Like in the Python docs, detailed descriptions of method parameters, return values, etc. are encouraged. Documentation is structured using Doxygen’s built-in commands rather than headers.
  • File-level comments, in particular the @file and @author tags, are no longer required or encouraged.

We haven’t made any breaking changes to the configuration of Doxygen itself, so previously written comments will build as before.


Might be handy for a doxygen-expert SublimeText user to provide a configuration for their favorite SublimeText doxygen plugin. I’ve been generally happy with DoxyDoxygen, but I haven’t tried others, nor configured it to our usage.