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 obsolecence), 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.