From patchwork Wed Dec 12 11:09:35 2018 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Patchwork-Submitter: Jacopo Mondi X-Patchwork-Id: 38 Return-Path: Received: from relay10.mail.gandi.net (relay10.mail.gandi.net [217.70.178.230]) by lancelot.ideasonboard.com (Postfix) with ESMTPS id B566060B13 for ; Wed, 12 Dec 2018 12:09:54 +0100 (CET) Received: from w540.lan (2-224-242-101.ip172.fastwebnet.it [2.224.242.101]) (Authenticated sender: jacopo@jmondi.org) by relay10.mail.gandi.net (Postfix) with ESMTPSA id 3C77E24000E; Wed, 12 Dec 2018 11:09:54 +0000 (UTC) From: Jacopo Mondi To: libcamera-devel@lists.libcamera.org Date: Wed, 12 Dec 2018 12:09:35 +0100 Message-Id: <1544612976-27101-2-git-send-email-jacopo@jmondi.org> X-Mailer: git-send-email 2.7.4 In-Reply-To: <1544612976-27101-1-git-send-email-jacopo@jmondi.org> References: <1544612976-27101-1-git-send-email-jacopo@jmondi.org> Subject: [libcamera-devel] [PATCH v4 1/2] Documentation: Add coding style document X-BeenThere: libcamera-devel@lists.libcamera.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 12 Dec 2018 11:09:54 -0000 Add document to summarize the coding style adopted by libcamera. Signed-off-by: Jacopo Mondi Reviewed-by: Laurent Pinchart Reviewed-by: Niklas Söderlund --- Documentation/coding-style.rst | 80 ++++++++++++++++++++++++++++++++++++++++++ Documentation/index.rst | 1 + Documentation/meson.build | 1 + 3 files changed, 82 insertions(+) create mode 100644 Documentation/coding-style.rst diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst new file mode 100644 index 0000000..4747927 --- /dev/null +++ b/Documentation/coding-style.rst @@ -0,0 +1,80 @@ +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" with the maximum line length set to 120 columns + * 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 c9b7c1c..ba6c6c6 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 578c1ca..3b87619 100644 --- a/Documentation/meson.build +++ b/Documentation/meson.build @@ -5,6 +5,7 @@ endif if sphinx.found() docs_sources = [ + 'coding-style.rst', 'conf.py', 'contributing.rst', 'index.rst',