[v3,02/11] Added External References section

Submitted by Christophe de Dinechin on Feb. 8, 2018, 11:25 a.m.

Details

Message ID 20180208112531.19601-3-christophe@dinechin.org
State New
Headers show
Series "Updates to the style guide" ( rev: 2 1 ) in Spice

Not browsing as part of any series.

Commit Message

Christophe de Dinechin Feb. 8, 2018, 11:25 a.m.
From: Christophe de Dinechin <dinechin@redhat.com>

Signed-off-by: Christophe de Dinechin <dinechin@redhat.com>
---
 docs/spice_style.txt | 20 ++++++++++++++++++++
 1 file changed, 20 insertions(+)

Patch hide | download patch | download mbox

diff --git a/docs/spice_style.txt b/docs/spice_style.txt
index f5d13642..10bfbc9a 100644
--- a/docs/spice_style.txt
+++ b/docs/spice_style.txt
@@ -6,6 +6,26 @@  Licensed under a Creative Commons Attribution-Share Alike 3.0
 United States License (see http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
 
 
+External references
+-------------------
+
+In general, unless otherwise noted here (e.g. the use of tabs),
+
+- For C code, SPICE follows the Linux kernel coding conventions as documented here: https://www.kernel.org/doc/html/v4.10/process/coding-style.html.
+  Notable deviations from the Linux coding style include:
+  + The use of 4 spaces for indentation instead of tabs
+  + The use of typedefs for structs not considered as a mistake
+  + The use of CamelCase for struct and class names
+
+- For C++ code, SPICE follows the LLVM coding standard (https://llvm.org/docs/CodingStandards.html).
+  Notable deviations from the LLVM coding style include:
+  + The format of header comments
+  + The placement of braces after functions and classes (follows the Linux style)
+
+In addition, for C++, developers should be aware of the C++ Core Guidelines and consider them as best practice unless otherwise agreed on by the team
+https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md
+
+
 Source Files
 ------------
 

Comments

> 
> From: Christophe de Dinechin <dinechin@redhat.com>
> 
> Signed-off-by: Christophe de Dinechin <dinechin@redhat.com>
> ---
>  docs/spice_style.txt | 20 ++++++++++++++++++++
>  1 file changed, 20 insertions(+)
> 
> diff --git a/docs/spice_style.txt b/docs/spice_style.txt
> index f5d13642..10bfbc9a 100644
> --- a/docs/spice_style.txt
> +++ b/docs/spice_style.txt
> @@ -6,6 +6,26 @@ Licensed under a Creative Commons Attribution-Share Alike
> 3.0
>  United States License (see
>  http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
>  
>  
> +External references
> +-------------------
> +
> +In general, unless otherwise noted here (e.g. the use of tabs),
> +
> +- For C code, SPICE follows the Linux kernel coding conventions as
> documented here:
> https://www.kernel.org/doc/html/v4.10/process/coding-style.html.
> +  Notable deviations from the Linux coding style include:
> +  + The use of 4 spaces for indentation instead of tabs
> +  + The use of typedefs for structs not considered as a mistake
> +  + The use of CamelCase for struct and class names
> +
> +- For C++ code, SPICE follows the LLVM coding standard
> (https://llvm.org/docs/CodingStandards.html).
> +  Notable deviations from the LLVM coding style include:
> +  + The format of header comments
> +  + The placement of braces after functions and classes (follows the Linux
> style)
> +

No, we don't follow some style defined by somebody else, maybe
our style is accidentally similar to these styles, I don't see
the point of specifying this here.
We are trying to define a style that works in C and C++ the paragraph
above is confusing, seems we are using 2 different styles.

> +In addition, for C++, developers should be aware of the C++ Core Guidelines
> and consider them as best practice unless otherwise agreed on by the team
> +https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md
> +

Make sense.

> +
>  Source Files
>  ------------
>  

Frediano
> On 9 Feb 2018, at 10:50, Frediano Ziglio <fziglio@redhat.com> wrote:
> 
>> 
>> From: Christophe de Dinechin <dinechin@redhat.com>
>> 
>> Signed-off-by: Christophe de Dinechin <dinechin@redhat.com>
>> ---
>> docs/spice_style.txt | 20 ++++++++++++++++++++
>> 1 file changed, 20 insertions(+)
>> 
>> diff --git a/docs/spice_style.txt b/docs/spice_style.txt
>> index f5d13642..10bfbc9a 100644
>> --- a/docs/spice_style.txt
>> +++ b/docs/spice_style.txt
>> @@ -6,6 +6,26 @@ Licensed under a Creative Commons Attribution-Share Alike
>> 3.0
>> United States License (see
>> http://creativecommons.org/licenses/by-sa/3.0/us/legalcode).
>> 
>> 
>> +External references
>> +-------------------
>> +
>> +In general, unless otherwise noted here (e.g. the use of tabs),
>> +
>> +- For C code, SPICE follows the Linux kernel coding conventions as
>> documented here:
>> https://www.kernel.org/doc/html/v4.10/process/coding-style.html.
>> +  Notable deviations from the Linux coding style include:
>> +  + The use of 4 spaces for indentation instead of tabs
>> +  + The use of typedefs for structs not considered as a mistake
>> +  + The use of CamelCase for struct and class names
>> +
>> +- For C++ code, SPICE follows the LLVM coding standard
>> (https://llvm.org/docs/CodingStandards.html).
>> +  Notable deviations from the LLVM coding style include:
>> +  + The format of header comments
>> +  + The placement of braces after functions and classes (follows the Linux
>> style)
>> +
> 
> No, we don't follow some style defined by somebody else, maybe
> our style is accidentally similar to these styles, I don't see
> the point of specifying this here.

The styles I reference are *much more* extensively documented than our own, and well known to many developers. So that means we don’t waste time specifying anything but the points where we diverge. It’s much less work for us, and clarifies many choices that are currently left open.

Ideally, I would like to have no coding guidelines of our own. It’s really not our business and a big waste of time.

Also, it’s no accident if we follow the same style, it’s really the traditional Unix style.


> We are trying to define a style that works in C and C++ the paragraph
> above is confusing, seems we are using 2 different styles.

Well, we are (although arguably we don’t really have a “style” for C++ yet).

> 
>> +In addition, for C++, developers should be aware of the C++ Core Guidelines
>> and consider them as best practice unless otherwise agreed on by the team
>> +https://github.com/isocpp/CppCoreGuidelines/blob/master/CppCoreGuidelines.md
>> +
> 
> Make sense.
> 
>> +
>> Source Files
>> ------------
>> 
> 
> Frediano