Coding Conventions

C++ Features

• Don't use exceptions
• Prefer solutions from the Qt library over Boost/others in Qt dependent code
  • In Avogadro use the C++11 features where necessary, they fall back to Boost on older compilers
  • 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
• Submit proposed topics to Gerrit
  • Monitor the CDash@Home builds and nightly builds once merged to ensure support in all supported compilers

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

Namespaces

• 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;

Casting

• 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

Aesthetics

• 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 what an argument is for
• Avoid abbreviations, as they are often ambiguous and we can afford the extra bytes