C++ Style Guide Update

Data Management DM Notifications
#1

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.

2 Likes
#2

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.