Skip to content

CTA Coding ConventionsΒΆ

Copied from GitLab issue #34, 15 Dec 2016

  • One class per file, so no nested classes unless small (<20 lines) helper classes (used only within one source file)
  • Use only cta::exception throughout the code (remove all castor::exceptions and in general all castor dependencies and references)
  • Class comment for each class (so one per file), unless obvious
  • Methods comments optional and only in base classes, and no need to put params and return comments
  • In general parameter and variable comments should be avoided (because of overhead and obsolescence), replaced by clear unambiguous names
  • Method and function names should also be meaningful and unambiguous
  • In general comment the "why" (where needed) and not the "what"
  • Always use newline and curly brackets even in single statement if's
  • Do not indent namespaces and private/public class areas (private/public keywords go at the same level of class keyword)
  • The maximum length of a source code line is 120 characters.
  • Header file comments must use Doxygen syntax. For example:
/**
 * This method says hello mum
 *
 * @param bla This little parameter went to market.
 * @return The rest of the story
 */
int helloMum(const std::string& bla);

/**
 * The cleanest structure ever written and documented.
 */
struct Cleanest {
  /**
   * A documented member variable.
   */
  std::string memberVariable;
};
  • Always put forward declarations in the file that uses them.
  • When implementing namespaced entities within a cpp file, put the necessary surrounding namespace {} clauses. The contents of a namespace clause should NOT be indented, for example:
namespace cta {
namespace catalogue {

//------------------------------------------------------------------------------
// addNameToIdx
//------------------------------------------------------------------------------
void ColumnNameToIdx::add(const std::string &name, const int idx) {
  if(m_nameToIdx.end() != m_nameToIdx.find(name)) {
    exception::Exception ex;
    ex.getMessage() << __FUNCTION__ << " failed: Column name " << name <<
    " is a duplicate";
    throw ex;
  }
  m_nameToIdx[name] = idx;
}

//------------------------------------------------------------------------------
// getIdx
//------------------------------------------------------------------------------
int ColumnNameToIdx::getIdx(const std::string &name) const {
  auto it = m_nameToIdx.find(name);
  if(m_nameToIdx.end() == it) {
    exception::Exception ex;
    ex.getMessage() << __FUNCTION__ << " failed: Unknown column name " << name;
    throw ex;
  }
  return it->second;
}

} // namespace catalogue
} // namespace cta
  • In include headers use <> for external and system headers and "" for CTA headers.
#include <memory>
#include <iostream>

#include <google/protobuf/stubs/common.h>
#include <xrootd/XrdCl/XrdClURL.hh>

#include "common/utils/strerror_r_wrapper.hpp"
#include "common/utils/utils.hpp"
  • CTA code includes must use the full path to the file from the project root. Do not use relative file locations.