Documentation: Add coding style document

Add document to summarize the coding style adopted by libcamera.

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>
Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>
Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>

1 files changed, 81 insertions, 0 deletions

diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst
new file mode 100644
index 00000000..d03eb3d5
--- /dev/null
+++ b/Documentation/coding-style.rst
@@ -0,0 +1,81 @@
+Coding Style Guidelines
+=======================
+
+The libcamera project has high standards of stability, efficiency and
+reliability. To achieve those, the project goes to great length to produce
+code that is as easy to read, understand and maintain as possible.
+
+These coding guidelines are meant to ensure code quality. As a contributor
+you are expected to follow them in all code submitted to the project. While
+strict compliance is desired, exceptions are tolerated when justified with
+good reasons. Please read the whole coding guidelines and use common sense
+to decide when departing from them is appropriate.
+
+libcamera is written in C++, a language that has seen many revisions and
+offers an extensive set of features that are easy to abuse. These coding
+guidelines establish the subset of C++ used by the project.
+
+
+Coding Style
+------------
+
+Even if the programming language in use is different, the project embraces the
+`Linux Kernel Coding Style`_ with a few exception and some C++ specificities.
+
+.. _Linux Kernel Coding Style: https://www.kernel.org/doc/html/latest/process/coding-style.html
+
+In particular, from the kernel style document, the following section are adopted:
+
+  * 1 "Indentation"
+  * 2 "Breaking Long Lines" striving to fit code within 80 columns and
+    accepting up to 120 columns when necessary
+  * 3 "Placing Braces and Spaces"
+  * 3.1 "Spaces"
+  * 8 "Commenting" with the exception that in-function comments are not
+    always un-welcome.
+
+While libcamera uses the kernel coding style for all typographic matters, the
+project is a user space library, developed in a different programming language,
+and the kernel guidelines fall short for this use case.
+
+For this reason, rules and guidelines from the `Google C++ Style Guide`_ have
+been adopted as well as most coding principles specified therein, with a
+few exceptions and relaxed limitations on some subjects.
+
+.. _Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html
+
+The following exceptions apply to the naming conventions specified in the
+document:
+
+  * File names: libcamera uses the .cpp extensions for C++ source files and
+    the .h extension for header files
+  * Variables, function parameters, function names and class members use
+    camel case style, with the first letter in lower-case (as in 'camelCase'
+    and not 'CamelCase')
+  * Types (classes, structs, type aliases, and type template parameters) use
+    camel case, with the first letter in capital case (as in 'CamelCase' and
+    not 'camelCase')
+  * Enum members use 'CamelCase', while macros are in capital case with
+    underscores in between
+  * All formatting rules specified in the selected sections of the Linux kernel
+    Code Style for indentation, braces, spacing, etc
+  * Header guards are formatted as '__LIBCAMERA_FILE_NAME_H__'
+
+
+C++ Specific Rules
+------------------
+
+The code shall be implemented in C++03, extended with the following
+C++-11-specific features:
+
+  * Initializer lists
+  * Type inference (auto and decltype)
+    Type inference shall be used with caution, to avoid drifting towards an
+    untyped language.
+  * Range-based for loop
+  * Lambda functions
+  * Explicit overrides and final
+  * Null pointer constant
+  * General-purpose smart pointers (std::unique_ptr), deprecating std::auto_ptr.
+    Smart pointers, as well as shared pointers and weak pointers, shall not be
+    overused.