summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJacopo Mondi <jacopo@jmondi.org>2018-12-10 11:32:05 +0100
committerJacopo Mondi <jacopo@jmondi.org>2018-12-13 09:00:07 +0100
commitee5662240103bae0f9e644969d37d0a3e9c48d88 (patch)
treedf8b63f977feeca0c516420f0cd0421bb10c6431
parent3b56ddaa96fbccf4eada05d378ddaa1cb6209b57 (diff)
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>
-rw-r--r--Documentation/coding-style.rst81
-rw-r--r--Documentation/index.rst1
-rw-r--r--Documentation/meson.build1
3 files changed, 83 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.
diff --git a/Documentation/index.rst b/Documentation/index.rst
index c9b7c1cd..ba6c6c6e 100644
--- a/Documentation/index.rst
+++ b/Documentation/index.rst
@@ -20,6 +20,7 @@ systems, including traditional Linux distributions, ChromeOS and Android.
:maxdepth: 2
:caption: Contents:
+ coding-style
contributing
diff --git a/Documentation/meson.build b/Documentation/meson.build
index d3ea5ea3..8264b5e6 100644
--- a/Documentation/meson.build
+++ b/Documentation/meson.build
@@ -41,6 +41,7 @@ endif
if sphinx.found()
docs_sources = [
+ 'coding-style.rst',
'conf.py',
'contributing.rst',
'index.rst',