documentation/C++GUIDE.md

CERC C++ Style Guide

What's coding style and why it matters.

Coding style is just how the code looks, it's incredibly personal, and everyone has their style.

Your preferred architectures, variable and function naming style all of then impacts in your code style and how the others read and understand it, so it could become a significant burden if everyone is coding on his or her own.

At CERC, we are following the Google C++ Style Guide and C++ Core Guide lines as a general reference.

Tools.

We use Visual Studio Code as an integrated development but any platform independent IDE can be used.

For code analysis, we encourage the usage of Valgrind whenever possible (Linux and Mac only).

Naming convention.

• Name your folders and files in lowercase and use _ (underscore) to separate words following the snake_case convention.
• Your class names must start in capital letters and follow the UpperCamelCase convention.
• Methods and properties that return collections must end in "s". Therefore, those that return single values, must be singular.
• Methods variables and properties should be lowercase and use _ (underscore) as a word separator following the snake_case convention.
• Constant names must be all capitals and use _ (underscore) to separate words following the CONSTANT_CASE convention.
• Name your getter and setter methods starting with "get_" and "set_" and following by the variable name.
• Private methods, variables and properties should be lowercase and use _ (underscore) as a word separator following the snake_case convention.

Files.

Naming

We enforce to keep just one class per file and consistent naming among them, we use cpp and hpp extensions for code and headers.

Example: To define a class named Person, two files need to be created following the naming conventions for files

  person.cpp
  person.hpp

No other classes will be defined in those files.

Header guards

All header files, should include header guards to prevent douple inclusions along your code.

/*
SPDX - License - Identifier: GPL-3.0-or-later
Copyright © 2022 Concordia CERC group
Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
*/

#ifndef SAMPLE_PERSON_HPP_
#define SAMPLE_PERSON_HPP_

...

#endif  //SAMPLE_PERSON_HPP_

Namespaces

We enforce the use of namespaces to organize our c++ code.

/*
SPDX - License - Identifier: GPL-3.0-or-later
Copyright © 2022 Concordia CERC group
Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
*/

#ifndef SAMPLE_PERSON_HPP_
#define SAMPLE_PERSON_HPP_

namespace sample {


}

#endif  //SAMPLE_PERSON_HPP_

Indentation

We indent with 2 spaces as it's considered more consistent when using different editors and operationg systems while provide enoug readability for the hierarchies.

Usage of using-clause

Usage of using-clause (#using) it's discouraged, as it's considered a bad practice that may cause namespace poisoning.

Imports.

Import placement

In .hpp files, place your imports at the top of the file, after the license and contact information, and protected by the header guard, place only the includes that are visible by your class definition.

/*
SPDX - License - Identifier: GPL-3.0-or-later
Copyright © 2022 Concordia CERC group
Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
*/

#ifndef SAMPLE_PERSON_HPP_
#define SAMPLE_PERSON_HPP_

#include <string>

namespace sample {


}

#endif  //SAMPLE_PERSON_HPP_

In .cpp files, place your imports at the top of the file, after the license and contact information, place only the includes that aren't already added in your header file (.hpp).

/*
SPDX - License - Identifier: GPL-3.0-or-later
Copyright © 2022 Concordia CERC group
Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
*/

#include <memory>
#include "person.hpp"

namespace sample {


}

Ensure that your imports are used and remove any unused.

Multiplatform

CERC team is aiming to create platform independent open software, therefore the use of platform specific libraries is discouraged, if such thing can't be avoided, try to provide platform alternatives by using compiler directives.

/*
SPDX - License - Identifier: GPL-3.0-or-later
Copyright © 2022 Concordia CERC group
Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
*/

#include <memory>
#include "person.hpp"
#ifdef __WIN32__
  #include <windows_specific_lib.h>
#ifdef __MACH__
  #include <mac_alternative_lib.h>
#endif
#ifdef __linux__
  #include <linux_alternative_lib.h>
#endif
}

Modern C++

Modern C++ solves lot's of issues with clasic C++ specially related to multiplatform code and memory handling, therefore it's highly recomended to use modern C++ instead of clasic whenever is possible.

Boost libraries are great, they offer a lot of great functionality, unfortunately, they still present a lack of uniformity among platforms and compiler versions therefore it's recomended to use standard alternatives whernever is possible.

Comments.

Code documentation.

All public classes, properties, and methods must have code comments in the header files, we are using doxygen for auto documentation and the code comments must start with capital letters and /// syntax is preferred

File include for documentation needs to be added only in the hpp files, after the license and contact information.

.hpp Example

/*
SPDX - License - Identifier: GPL-3.0-or-later
Copyright © 2022 Concordia CERC group
Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
*/

/// \file person.hpp

#ifndef SAMPLE_PERSON_HPP_
#define SAMPLE_PERSON_HPP_

#include <string>

namespace sample {
  /// Person class description
  class Person 
  {
    public:
      /// @brief Person constructor      
      /// @param Person name
      Person(std::string name);
      /// @brief Retrieve person name
      std::string get_name();
    private:
      std::string name;
  }
}

#endif  //SAMPLE_PERSON_HPP_

Attributes with known units should be explicit in method's comment.

/*
SPDX - License - Identifier: GPL-3.0-or-later
Copyright © 2022 Concordia CERC group
Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
*/

/// \file person.hpp

#ifndef SAMPLE_PERSON_H_
#define SAMPLE_PERSON_H_

#include <string>

namespace sample {
  class Person 
  {
    public:
      /// @brief Person constructor      
      /// @param Person name
      Person(std::string name);
      /// @brief Retrieve person name
      std::string get_name();
      /// @brief Age in years
      int age;
    private:
      std::string name;
  }
}

To do's.

Pending to implement or correct operations should be indicated with TODO comments to highlight the missing functionality.

  // TODO: do something about a topic