[libcamera-devel,v4,1/2] Documentation: Add coding style document

38 diff mbox series

Add document to summarize the coding style adopted by libcamera.

Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
---
 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

Hi Jacopo,

Thank you for the patch.

On Wednesday, 12 December 2018 13:09:35 EET Jacopo Mondi wrote:
> Add document to summarize the coding style adopted by libcamera.
> 
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  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

We have agreed to treat the 80 columns limit as a soft limit, but I would 
still mention it here. How about

  * 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__'

Nitpicking, some items end with a period, some don't.

With these fixed,

Reviewed-by: Laurent Pinchart <laurent.pinchart@ideasonboard.com>

and feel free to push.

> +
> +
> +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',

Hi Jacopo,

Thanks for your patch.

On 2018-12-12 12:09:35 +0100, Jacopo Mondi wrote:
> Add document to summarize the coding style adopted by libcamera.
> 
> Signed-off-by: Jacopo Mondi <jacopo@jmondi.org>
> ---
>  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.

This sentence do not make sens to me. Are you missing a '.' after 
std::auto_ptr ?  With this fixed:

Reviewed-by: Niklas Söderlund <niklas.soderlund@ragnatech.se>

> 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',
> -- 
> 2.7.4
> 
> _______________________________________________
> libcamera-devel mailing list
> libcamera-devel@lists.libcamera.org
> https://lists.libcamera.org/listinfo/libcamera-devel