From 4a782d30931ddc6c02bcb09c67363473db360ce7 Mon Sep 17 00:00:00 2001
From: Noelia <noelia@status.im>
Date: Tue, 3 May 2022 16:14:31 +0200
Subject: [PATCH] docs(general-cpp): Initial proposal / best general and cpp
 practices

Basic list of general and cpp specific rules and best practices for contributors.
---
 src/contributing.md | 96 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 96 insertions(+)
 create mode 100644 src/contributing.md

diff --git a/src/contributing.md b/src/contributing.md
new file mode 100644
index 0000000000..654ff07008
--- /dev/null
+++ b/src/contributing.md
@@ -0,0 +1,96 @@
+# Contributing guidelines
+The main goal of the following document is to have a `basic set of guidelines` that all contributors should apply when writing code in the `status-desktop` project and specific rules for using the C++ language in order to achieve consistent, maintainable and easy-to-understand code for everyone.
+
+There are lots of existing and extended guidelines that can be used, as well, as a complement of the ones that will be described below. Here some examples:
+- [Cpp Core Guidelines](https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md)
+
+## Generic rules
+
+General software development best practices and / or OPP specific ones:
+- Write code using a syntax that can make the `code easy to understand` although it requires more writing. The time spent to understand that code by other contributors will be compensated.
+- Create `self-documented` code by using self-explanatory names wherever possible for classes, methods and variables. It will increase readability and comprehension.
+- Keep in mind the `SOLID` principles. Your code will become flexible, reusable, scalable and prepared for test-driven development.
+- Keep `methods body short`. Divide when possible. Recursive calls and nested loops should be minimized.
+- Use `parenthesis` to resolve ambiguity in complex expressions. Each individual expression should be written in its single parenthesis.
+- Use the following `arguments order` in method's `signature` (it will force default argument's values to be input ones): 
+  - Input / Output.
+  - Output.
+  - Input.
+- `Initialize` all `variables` when declared.
+- `Initialize` all class `attributes` in their own class constructor.
+- Use `m_` syntaxis to define attribute names.
+- Class and method names should begin with `capital letter` and use `camel case` approach.
+- Use the following `class / members declaration structure`:
+  - Public methods / members.
+  - Protected methods / members.
+  - Private methods / members. 
+- Code should compile `without warnings`.
+
+
+## C++ language specific rules
+- As a general rule, for `smart pointers`, `containers` and `threads`, use `STL for domain` and `Qt specific for controllers` (layer exposed to QML).
+  - Use smart pointers for general dynamic/heap memory management: STL with make_shared and make_unique. 
+  - Use Qt’s parent-child relationship and built-in ownership in API where appropriate: QObject-based with QPointer.
+- Use `const` keyword wherever possible it will build a more robust code. If it is used in variables, the held value cannot be modified; in pointers, the address pointed to cannot be modified (no restrictions for the stored data); in class methods, the method cannot modify any class attribute.
+- When passing arguments, use `references` instead of pointers as far as possible by using `&`. It will prevent some typical errors such as passing null pointers to methods.
+- When passing arguments, `avoid passing by value` big size arguments as structures and objects. It will reduce the stack used and it will not be necessary to have properly implemented the copy constructor in all classes. 
+- Use `dynamic allocation` only if needed because it requires much processor time than stack memory allocation. By minimizing its usage for variables and objects will increase efficiency and `reduce` the risk of `memory leaks`.
+- `Thread’s` usage must be `justified`. Always keep in mind the principle “Keep It Simple”.
+- The `C++ standard` to be used must be `at least C++17`.
+- `Singleton’s` usage must be `justified`. They must be just only global settings and specific objects but to use them it will need a consensus with the team.
+- `.clang-tidy` configuration will be used as the C++ linter and at least the following checkers will be set (it must be included in the CI process):
+  - cppcoreguidelines-*
+  - modernize-*
+  - readibility-*
+
+## Documentation
+
+- Use `header files` to document classes and methods by using `doxygen syntax`. More information here: [Doxygen manual](https://www.doxygen.nl/index.html).
+
+
+```
+/*
+ * Add here header file description.
+ * \file Example.h
+ * \brief Source code file.
+ */
+
+ ...
+
+/*
+ * \brief Add here short class description.
+ * This class implements a ...
+ */
+ class Example {
+    public:
+        /*
+        * \brief Class constructor
+        */
+        Example();
+
+        /*
+        * \brief Class destructor.
+        */
+        ~Example();
+
+    protected:
+        /*
+        * \brief Add here short method description.
+        * This method ...
+        * \return True if the operation was successfully completed; False otherwise.
+        */
+        bool Example2();
+
+    private:
+        /*
+        * \brief Add here short method description.
+        * This method...
+        */
+        Example3(bool bEnabled  //!< [in] Enable argument value.           
+        );
+
+    ...
+ }
+```
+
+