Coding Conventions (C++)#

C++ Features#

  • Don’t use exceptions or asserts - Avogadro is production code and should never crash

  • Prefer solutions from the Qt library over Boost/others in Qt dependent code

    • In Avogadro use the C++11 and C++17 features where necessary.

    • Avogadro offers AVO_OVERRIDE and AVO_FINAL (defines for new C++11 override and final)

  • Minimize dependencies on third party libraries, think carefully before adding more

  • Use templates where they make sense

Including Headers#

  • In public headers, always use this form to include project headers: #include <avogadro/core/something.h>

  • Prefer declaration of types in public headers over including headers for the type

namespace Avogadro {
class MyClass;
  • In source files include specialized headers first, then dependency headers, then generic headers

#include "myapiheader.h" // Our header
#include <avogadro/core/molecule.h> // Avogadro header from a different module
#include <QtCore/QString> // Qt header
#include <vector> // STL

Export Macro Headers#

  • If you need to include the export header for the module do it as the first include

#include "avogadrorenderingexport.h"

Private Headers#

  • Private headers are denoted by _p.h endings, and should not be included in public headers

Qt Headers#

  • Use the Qt module and camel-cased header

  • Never include Qt module headers such as QtGui, instead include the header for the class being used

#include <QtGui> // WRONG (module header)!
#include <QtGui/QDialog> // Correct


  • Open Chemistry code is namespaced

  • Avogadro uses nested namespaces

    • Everything is inside the Avogadro namespace

    • Code in the core module is in the Avogadro::Core namespace

  • MoleQueue and MongoChem use a namespace to contain most code

  • Don’t overspecify, i.e. code in the Avogadro namespace doesn’t need to use Avogadro:

    • Qt signals and slots are one exception where MOC often needs a little help

  • Never use using inside a public header

    • Only pull in specific symbols in source files, i.e. using Avogadro::Core::Molecule;


  • Avoid C-style casts, prefer C++ (static_cast, dynamic_cast, const_cast, reinterpret_cast)

  • For Qt classes, and Qt derived classes prefer qobject_cast over dynamic_cast


  • Prefer enums to define constants over static const int or #defines

  • Prefer verbose argument names in headers

    • Most IDEs show the argument names in their autocompletion

    • It looks better in the generated documentation

    • Poor style making people guess the purpose of an argument

  • Avoid abbreviations, as they are often ambiguous and we can afford a few extra bytes