Upload New File

2022-11-11 16:18:48 +00:00 · 2022-11-11 16:18:48 +00:00 · 8466665e17
commit 8466665e17
parent bfef262727
1 changed files with 278 additions and 0 deletions
--- a/C++GUIDE.md
+++ b/C++GUIDE.md
@ -0,0 +1,278 @@
+# 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](https://google.github.io/styleguide/cppguide.html#Namespace_Names) and [C++ Core Guide lines](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines) as a general reference.
+
+## Tools.
+
+We use [Visual Studio Code](https://code.visualstudio.com/) as an integrated development but any platform independent IDE can be used.
+
+For code analysis, we encourage the usage of [Valgrind](https://valgrind.org/) 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.
+
+```c++
+/*
+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_H_
+#define SAMPLE_PERSON_H_
+
+...
+
+#endif  //SAMPLE_PERSON_H_
+
+```
+
+###
+
+### Namespaces
+
+We enforce the use of namespaces to organize our c++ code.
+
+```c++
+/*
+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_H_
+#define SAMPLE_PERSON_H_
+
+namespace sample {
+
+
+}
+
+#endif  //SAMPLE_PERSON_H_
+
+```
+
+### 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.
+
+```c++
+/*
+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_H_
+#define SAMPLE_PERSON_H_
+
+#include <string>
+
+namespace sample {
+
+
+}
+
+#endif  //SAMPLE_PERSON_H_
+
+```
+
+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).
+
+```c++
+/*
+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.
+
+```c++
+/*
+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>
+
+[Boost libraries](https://www.boost.org/) 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](https://www.doxygen.nl) for auto documentation and the code comments must start with capital letters and /// syntax is preferred
+
+File include for documentation needs to be added in both hpp and cpp files, after the license and contact information.
+
+##### .hpp Example
+
+```c++
+/*
+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();
+    private:
+      std::string name;
+  }
+}
+
+#endif  //SAMPLE_PERSON_H_
+
+```
+
+##### .cpp Example
+
+```c++
+/*
+SPDX - License - Identifier: GPL-3.0-or-later
+Copyright © 2022 Concordia CERC group
+Project Coder Guillermo Gutierrez Morote <Guillermo.GutierrezMorote@concordia.ca>
+*/
+
+/// \file person.cpp
+
+#include <memory>
+#include "person.hpp"
+
+namespace sample {
+  Person::Person(std::string name)
+  {
+    this->name = name;
+  }
+
+  Person::get_name()
+  {
+    return this->name;
+  }
+
+}
+```
+
+Attributes with known units should be explicit in method's comment.
+
+```c++
+/*
+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.
+
+```c++
+  // TODO: do something about a topic
+```
+