[{"id":47,"web_url":"https://patchwork.libcamera.org/comment/47/","msgid":"<154467122.SR1XcBeIfC@avalon>","date":"2018-12-12T19:19:32","subject":"Re: [libcamera-devel] [PATCH v4 1/2] Documentation: Add coding\n\tstyle document","submitter":{"id":2,"url":"https://patchwork.libcamera.org/api/people/2/","name":"Laurent Pinchart","email":"laurent.pinchart@ideasonboard.com"},"content":"Hi Jacopo,\n\nThank you for the patch.\n\nOn Wednesday, 12 December 2018 13:09:35 EET Jacopo Mondi wrote:\n> Add document to summarize the coding style adopted by libcamera.\n> \n> Signed-off-by: Jacopo Mondi \n> ---\n> Documentation/coding-style.rst | 80 +++++++++++++++++++++++++++++++++++++++\n> Documentation/index.rst | 1 +\n> Documentation/meson.build | 1 +\n> 3 files changed, 82 insertions(+)\n> create mode 100644 Documentation/coding-style.rst\n> \n> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst\n> new file mode 100644\n> index 0000000..4747927\n> --- /dev/null\n> +++ b/Documentation/coding-style.rst\n> @@ -0,0 +1,80 @@\n> +Coding Style Guidelines\n> +=======================\n> +\n> +The libcamera project has high standards of stability, efficiency and\n> +reliability. To achieve those, the project goes to great length to produce\n> +code that is as easy to read, understand and maintain as possible.\n> +\n> +These coding guidelines are meant to ensure code quality. As a contributor\n> +you are expected to follow them in all code submitted to the project. While\n> +strict compliance is desired, exceptions are tolerated when justified with\n> +good reasons. Please read the whole coding guidelines and use common sense\n> +to decide when departing from them is appropriate.\n> +\n> +libcamera is written in C++, a language that has seen many revisions and\n> +offers an extensive set of features that are easy to abuse. These coding\n> +guidelines establish the subset of C++ used by the project.\n> +\n> +\n> +Coding Style\n> +------------\n> +\n> +Even if the programming language in use is different, the project embraces\n> the\n> +`Linux Kernel Coding Style`_ with a few exception and some C++\n> specificities.\n> +\n> +.. _Linux Kernel Coding Style:\n> https://www.kernel.org/doc/html/latest/process/coding-style.html\n> +\n> +In particular, from the kernel style document, the following section are\n> adopted:\n> +\n> + * 1 \"Indentation\"\n> + * 2 \"Breaking Long Lines\" with the maximum line length set to 120 columns\n\nWe have agreed to treat the 80 columns limit as a soft limit, but I would \nstill mention it here. How about\n\n * 2 \"Breaking Long Lines\" striving to fit code within 80 columns and \naccepting up to 120 columns when necessary\n\n> + * 3 \"Placing Braces and Spaces\"\n> + * 3.1 \"Spaces\"\n> + * 8 \"Commenting\" with the exception that in-function comments are not\n> + always un-welcome.\n> +\n> +While libcamera uses the kernel coding style for all typographic matters,\n> the +project is a user space library, developed in a different programming\n> language, +and the kernel guidelines fall short for this use case.\n> +\n> +For this reason, rules and guidelines from the `Google C++ Style Guide`_\n> have +been adopted as well as most coding principles specified therein,\n> with a +few exceptions and relaxed limitations on some subjects.\n> +\n> +.. _Google C++ Style Guide:\n> https://google.github.io/styleguide/cppguide.html +\n> +The following exceptions apply to the naming conventions specified in the\n> +document:\n> +\n> + * File names: libcamera uses the .cpp extensions for C++ source files and\n> + the .h extension for header files.\n> + * Variables, function parameters, function names and class members use\n> + camel case style, with the first letter in lower-case (as in\n> 'camelCase'\n> + and not 'CamelCase')\n> + * Types (classes, structs, type aliases, and type template parameters)\n> use + camel case, with the first letter in capital case (as in\n> 'CamelCase' and + not 'camelCase').\n> + * Enum members use 'CamelCase', while macros are in capital case with\n> + underscores in between.\n> + * All formatting rules specified in the selected sections of the Linux\n> kernel + Code Style for indentation, braces, spacing, etc\n> + * Header guards are formatted as '__LIBCAMERA_FILE_NAME_H__'\n\nNitpicking, some items end with a period, some don't.\n\nWith these fixed,\n\nReviewed-by: Laurent Pinchart \n\nand feel free to push.\n\n> +\n> +\n> +C++ Specific Rules\n> +------------------\n> +\n> +The code shall be implemented in C++03, extended with the following\n> +C++-11-specific features:\n> +\n> + * Initializer lists\n> + * Type inference (auto and decltype)\n> + Type inference shall be used with caution, to avoid drifting towards an\n> + untyped language.\n> + * Range-based for loop\n> + * Lambda functions\n> + * Explicit overrides and final\n> + * Null pointer constant\n> + * General-purpose smart pointers (std::unique_ptr), deprecating\n> std::auto_ptr\n> + Smart pointers, as well as shared pointers and weak pointers, shall not\n> be\n> + overused.\n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index c9b7c1c..ba6c6c6 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -20,6 +20,7 @@ systems, including traditional Linux distributions,\n> ChromeOS and Android.\n> :maxdepth: 2\n> \n> :caption: Contents:\n> + coding-style\n> contributing\n> \n> \n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 578c1ca..3b87619 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -5,6 +5,7 @@ endif\n> \n> if sphinx.found()\n> docs_sources = [\n> + 'coding-style.rst',\n> 'conf.py',\n> 'contributing.rst',\n> 'index.rst',","headers":{"Return-Path":"","Received":["from perceval.ideasonboard.com (perceval.ideasonboard.com\n\t[213.167.242.64])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id EC83F60B0F\n\tfor ;\n\tWed, 12 Dec 2018 20:18:46 +0100 (CET)","from avalon.localnet (dfj612ybrt5fhg77mgycy-3.rev.dnainternet.fi\n\t[IPv6:2001:14ba:21f5:5b00:2e86:4862:ef6a:2804])\n\tby perceval.ideasonboard.com (Postfix) with ESMTPSA id 4FBCA55A;\n\tWed, 12 Dec 2018 20:18:46 +0100 (CET)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/simple; d=ideasonboard.com;\n\ts=mail; t=1544642326;\n\tbh=COaavXGyGCbumUvLPdS4+aGKR10+EblhW1FKNdXF1sI=;\n\th=From:To:Cc:Subject:Date:In-Reply-To:References:From;\n\tb=mmk+1uAHiSq+IxUKJJ0SBe7kJh5uBCHMfbqKS/cLlG2auZiDGCNaLsNaTxdFe+0we\n\tO+urRnIaIOims1QxK+aj4maN+JhbS/Y0R7BIuKxN0W/LNM9RqSiU3dlewbRNbEvQRo\n\tV904i4pqgW1XiH5VK5AEzLAQfacQ3D1BS3Egif/w=","From":"Laurent Pinchart ","To":"libcamera-devel@lists.libcamera.org","Date":"Wed, 12 Dec 2018 21:19:32 +0200","Message-ID":"<154467122.SR1XcBeIfC@avalon>","Organization":"Ideas on Board Oy","In-Reply-To":"<1544612976-27101-2-git-send-email-jacopo@jmondi.org>","References":"<1544612976-27101-1-git-send-email-jacopo@jmondi.org>\n\t<1544612976-27101-2-git-send-email-jacopo@jmondi.org>","MIME-Version":"1.0","Content-Transfer-Encoding":"7Bit","Content-Type":"text/plain; charset=\"us-ascii\"","Subject":"Re: [libcamera-devel] [PATCH v4 1/2] Documentation: Add coding\n\tstyle document","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Wed, 12 Dec 2018 19:18:47 -0000"}},{"id":48,"web_url":"https://patchwork.libcamera.org/comment/48/","msgid":"<20181213030254.GO17972@bigcity.dyn.berto.se>","date":"2018-12-13T03:02:54","subject":"Re: [libcamera-devel] [PATCH v4 1/2] Documentation: Add coding\n\tstyle document","submitter":{"id":5,"url":"https://patchwork.libcamera.org/api/people/5/","name":"Niklas Söderlund","email":"niklas.soderlund@ragnatech.se"},"content":"Hi Jacopo,\n\nThanks for your patch.\n\nOn 2018-12-12 12:09:35 +0100, Jacopo Mondi wrote:\n> Add document to summarize the coding style adopted by libcamera.\n> \n> Signed-off-by: Jacopo Mondi \n> ---\n> Documentation/coding-style.rst | 80 ++++++++++++++++++++++++++++++++++++++++++\n> Documentation/index.rst | 1 +\n> Documentation/meson.build | 1 +\n> 3 files changed, 82 insertions(+)\n> create mode 100644 Documentation/coding-style.rst\n> \n> diff --git a/Documentation/coding-style.rst b/Documentation/coding-style.rst\n> new file mode 100644\n> index 0000000..4747927\n> --- /dev/null\n> +++ b/Documentation/coding-style.rst\n> @@ -0,0 +1,80 @@\n> +Coding Style Guidelines\n> +=======================\n> +\n> +The libcamera project has high standards of stability, efficiency and\n> +reliability. To achieve those, the project goes to great length to produce\n> +code that is as easy to read, understand and maintain as possible.\n> +\n> +These coding guidelines are meant to ensure code quality. As a contributor\n> +you are expected to follow them in all code submitted to the project. While\n> +strict compliance is desired, exceptions are tolerated when justified with\n> +good reasons. Please read the whole coding guidelines and use common sense\n> +to decide when departing from them is appropriate.\n> +\n> +libcamera is written in C++, a language that has seen many revisions and\n> +offers an extensive set of features that are easy to abuse. These coding\n> +guidelines establish the subset of C++ used by the project.\n> +\n> +\n> +Coding Style\n> +------------\n> +\n> +Even if the programming language in use is different, the project embraces the\n> +`Linux Kernel Coding Style`_ with a few exception and some C++ specificities.\n> +\n> +.. _Linux Kernel Coding Style: https://www.kernel.org/doc/html/latest/process/coding-style.html\n> +\n> +In particular, from the kernel style document, the following section are adopted:\n> +\n> + * 1 \"Indentation\"\n> + * 2 \"Breaking Long Lines\" with the maximum line length set to 120 columns\n> + * 3 \"Placing Braces and Spaces\"\n> + * 3.1 \"Spaces\"\n> + * 8 \"Commenting\" with the exception that in-function comments are not\n> + always un-welcome.\n> +\n> +While libcamera uses the kernel coding style for all typographic matters, the\n> +project is a user space library, developed in a different programming language,\n> +and the kernel guidelines fall short for this use case.\n> +\n> +For this reason, rules and guidelines from the `Google C++ Style Guide`_ have\n> +been adopted as well as most coding principles specified therein, with a\n> +few exceptions and relaxed limitations on some subjects.\n> +\n> +.. _Google C++ Style Guide: https://google.github.io/styleguide/cppguide.html\n> +\n> +The following exceptions apply to the naming conventions specified in the\n> +document:\n> +\n> + * File names: libcamera uses the .cpp extensions for C++ source files and\n> + the .h extension for header files.\n> + * Variables, function parameters, function names and class members use\n> + camel case style, with the first letter in lower-case (as in 'camelCase'\n> + and not 'CamelCase')\n> + * Types (classes, structs, type aliases, and type template parameters) use\n> + camel case, with the first letter in capital case (as in 'CamelCase' and\n> + not 'camelCase').\n> + * Enum members use 'CamelCase', while macros are in capital case with\n> + underscores in between.\n> + * All formatting rules specified in the selected sections of the Linux kernel\n> + Code Style for indentation, braces, spacing, etc\n> + * Header guards are formatted as '__LIBCAMERA_FILE_NAME_H__'\n> +\n> +\n> +C++ Specific Rules\n> +------------------\n> +\n> +The code shall be implemented in C++03, extended with the following\n> +C++-11-specific features:\n> +\n> + * Initializer lists\n> + * Type inference (auto and decltype)\n> + Type inference shall be used with caution, to avoid drifting towards an\n> + untyped language.\n> + * Range-based for loop\n> + * Lambda functions\n> + * Explicit overrides and final\n> + * Null pointer constant\n> + * General-purpose smart pointers (std::unique_ptr), deprecating std::auto_ptr\n> + Smart pointers, as well as shared pointers and weak pointers, shall not be\n> + overused.\n\nThis sentence do not make sens to me. Are you missing a '.' after \nstd::auto_ptr ? With this fixed:\n\nReviewed-by: Niklas Söderlund \n\n> diff --git a/Documentation/index.rst b/Documentation/index.rst\n> index c9b7c1c..ba6c6c6 100644\n> --- a/Documentation/index.rst\n> +++ b/Documentation/index.rst\n> @@ -20,6 +20,7 @@ systems, including traditional Linux distributions, ChromeOS and Android.\n> :maxdepth: 2\n> :caption: Contents:\n> \n> + coding-style\n> contributing\n> \n> \n> diff --git a/Documentation/meson.build b/Documentation/meson.build\n> index 578c1ca..3b87619 100644\n> --- a/Documentation/meson.build\n> +++ b/Documentation/meson.build\n> @@ -5,6 +5,7 @@ endif\n> \n> if sphinx.found()\n> docs_sources = [\n> + 'coding-style.rst',\n> 'conf.py',\n> 'contributing.rst',\n> 'index.rst',\n> -- \n> 2.7.4\n> \n> _______________________________________________\n> libcamera-devel mailing list\n> libcamera-devel@lists.libcamera.org\n> https://lists.libcamera.org/listinfo/libcamera-devel","headers":{"Return-Path":"","Received":["from mail-lf1-x144.google.com (mail-lf1-x144.google.com\n\t[IPv6:2a00:1450:4864:20::144])\n\tby lancelot.ideasonboard.com (Postfix) with ESMTPS id D0A5860B0C\n\tfor ;\n\tThu, 13 Dec 2018 04:02:57 +0100 (CET)","by mail-lf1-x144.google.com with SMTP id y11so402994lfj.4\n\tfor ;\n\tWed, 12 Dec 2018 19:02:57 -0800 (PST)","from localhost (89-233-230-99.cust.bredband2.com. [89.233.230.99])\n\tby smtp.gmail.com with ESMTPSA id\n\tf29sm96084lfa.46.2018.12.12.19.02.55\n\t(version=TLS1_2 cipher=ECDHE-RSA-CHACHA20-POLY1305 bits=256/256);\n\tWed, 12 Dec 2018 19:02:55 -0800 (PST)"],"DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=ragnatech-se.20150623.gappssmtp.com; s=20150623;\n\th=date:from:to:cc:subject:message-id:references:mime-version\n\t:content-disposition:content-transfer-encoding:in-reply-to\n\t:user-agent; bh=3BMHooe5mvODJeeHzAq78YnPJe9XGedqINPfPoDSp24=;\n\tb=Dw/IqI7wRyCMT+96+un8upXi8b4SV87AWuNQJUa4jeMBhO5/9NithmCJjoy1pEGncK\n\tejwTqF0xoy84hd7PU/k6WmP0di73fCT0cm54G6IUncoTx6e8rD5uw6HeGpqQ8B2zxedm\n\tcktUHB4i/xUoj4FXbDl+EBEXHOpHcFjFQj8blO1KxeRxmIEOzONUKvLAAcKnqSl38Ov/\n\t8ekqFm4zOg1XcMUNH3y9oEWz/rVsewtF0u4VWGsKfFJsTulZLFiIiC2rx8u66n0h+yUf\n\tHapDu4dicANE0SwU/x7khhnX6TjhYPlU53ljzF+zJ0f7AMbAf16wBE02V0V99dx6vuJh\n\tiKlQ==","X-Google-DKIM-Signature":"v=1; a=rsa-sha256; c=relaxed/relaxed;\n\td=1e100.net; s=20161025;\n\th=x-gm-message-state:date:from:to:cc:subject:message-id:references\n\t:mime-version:content-disposition:content-transfer-encoding\n\t:in-reply-to:user-agent;\n\tbh=3BMHooe5mvODJeeHzAq78YnPJe9XGedqINPfPoDSp24=;\n\tb=s+Lc6hvaTnyD5uKEkgsQbZAdk3QyDPncRUCHlApSESy8qhaQk/d0CsXInljCGJFumK\n\tPbLm7VAR2B8PoR5DrOiuf75ptlZmTXJlZM0TSfk4FL8lX2b+ITzRhkgoX6tBIFommR4h\n\tzuDYlYYeY8NZOWEyz8MEKtbhFtkVrrrLF73GKaavT2xWDEeDxnU62GkmILVlTfr/K+pB\n\tQJez4e8lODvRnm28zA5LGa9/e22SLTbHMv+gW7A0zx/RIjs/7Q6sJsW/MrAVqOAb1M2P\n\tN3bqakF94aYhTHRh77Z0M3SVpHErsdgjLJYJKpAx02Ygeu3dAWt6BD8RoPZirbCi/Ib1\n\tgyqA==","X-Gm-Message-State":"AA+aEWbmM3iPUGG5yr3OTNVniM20iRJzXahNgnFrVNGLogJilNvtsO9I\n\tK7Hyx1qCUG7oiGigdN4n7M5PwujfVJg=","X-Google-Smtp-Source":"AFSGD/XO7l8kY2QsaHI8naOSMU5rVAaEW1qhBwk8LHpCWK6Xu9TzbXl9r2bt7zy0CyhWq7GaA1C9JQ==","X-Received":"by 2002:a19:2106:: with SMTP id h6mr12675606lfh.29.1544670176836;\n\tWed, 12 Dec 2018 19:02:56 -0800 (PST)","Date":"Thu, 13 Dec 2018 04:02:54 +0100","From":"Niklas =?iso-8859-1?q?S=F6derlund?= ","To":"Jacopo Mondi ","Cc":"libcamera-devel@lists.libcamera.org","Message-ID":"<20181213030254.GO17972@bigcity.dyn.berto.se>","References":"<1544612976-27101-1-git-send-email-jacopo@jmondi.org>\n\t<1544612976-27101-2-git-send-email-jacopo@jmondi.org>","MIME-Version":"1.0","Content-Type":"text/plain; charset=iso-8859-1","Content-Disposition":"inline","Content-Transfer-Encoding":"8bit","In-Reply-To":"<1544612976-27101-2-git-send-email-jacopo@jmondi.org>","User-Agent":"Mutt/1.10.1 (2018-07-13)","Subject":"Re: [libcamera-devel] [PATCH v4 1/2] Documentation: Add coding\n\tstyle document","X-BeenThere":"libcamera-devel@lists.libcamera.org","X-Mailman-Version":"2.1.23","Precedence":"list","List-Id":"","List-Unsubscribe":",\n\t","List-Archive":"","List-Post":"","List-Help":"","List-Subscribe":",\n\t","X-List-Received-Date":"Thu, 13 Dec 2018 03:02:58 -0000"}}]