[v4,10/12] Integrate suggestions from Christophe Fergeau

Submitted by Christophe de Dinechin on Feb. 15, 2018, 4:06 p.m.

Details

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

Not browsing as part of any series.

Commit Message

Christophe de Dinechin Feb. 15, 2018, 4:06 p.m.
From: Christophe de Dinechin <dinechin@redhat.com>

This attempts to find a wording that takes into account the existing
practice, notably in the server.

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

Patch hide | download patch | download mbox

diff --git a/docs/spice_style.txt b/docs/spice_style.txt
index c28d7be3..4c29a410 100644
--- a/docs/spice_style.txt
+++ b/docs/spice_style.txt
@@ -432,12 +432,22 @@  Headers should be protected against multiple inclusion using a macro that contai
 
 ...
 
-#endif // MY_MODULE_H
+#endif /* MY_MODULE_H */
 ----
 
-The macro may include additional information, e.g. a component. For example a file generally referenced as foo/bar.h could use a FOO_BAR_H macro.
+The macro may include additional information, e.g. a component. For
+example a file generally referenced as foo/bar.h could use a FOO_BAR_H
+macro.
+
+Historically, some headers added underscores liberally,
+e.g. MY_MODULE_H_. This is neither necessary nor discouraged, although
+as a reminder, a leading underscore followed by a capital letter is
+reserved for the implementation and should not be used, so
+_MY_MODULE_H is, technically speaking, invalid C.
+
+C++ headers and headers in new components should use // for the #endif comment.
+The server code consistently uses /* */ for the #endif comment, keep it that way.
 
-Historically, some headers added underscores liberally, e.g. MY_MODULE_H_. This is neither necessary nor discouraged, although as a reminder, a leading underscore followed by a capital letter is reserved for the implementation and should not be used, so _MY_MODULE_H is, technically speaking, invalid C.
 
 Header inclusion
 ----------------

Comments

The shortlog is not really good..

On Thu, Feb 15, 2018 at 05:06:23PM +0100, Christophe de Dinechin wrote:
> From: Christophe de Dinechin <dinechin@redhat.com>
> 
> This attempts to find a wording that takes into account the existing
> practice, notably in the server.
> 
> Signed-off-by: Christophe de Dinechin <dinechin@redhat.com>
> ---
>  docs/spice_style.txt | 16 +++++++++++++---
>  1 file changed, 13 insertions(+), 3 deletions(-)
> 
> diff --git a/docs/spice_style.txt b/docs/spice_style.txt
> index c28d7be3..4c29a410 100644
> --- a/docs/spice_style.txt
> +++ b/docs/spice_style.txt
> @@ -432,12 +432,22 @@ Headers should be protected against multiple inclusion using a macro that contai
>  
>  ...
>  
> -#endif // MY_MODULE_H
> +#endif /* MY_MODULE_H */
>  ----
>  
> -The macro may include additional information, e.g. a component. For example a file generally referenced as foo/bar.h could use a FOO_BAR_H macro.
> +The macro may include additional information, e.g. a component. For
> +example a file generally referenced as foo/bar.h could use a FOO_BAR_H
> +macro.
> +
> +Historically, some headers added underscores liberally,
> +e.g. MY_MODULE_H_. This is neither necessary nor discouraged, although
> +as a reminder, a leading underscore followed by a capital letter is
> +reserved for the implementation and should not be used, so
> +_MY_MODULE_H is, technically speaking, invalid C.

Just drop all of this, we want a guideline which says
"your header guards should be MY_MODULE_H".
We don't want a  guideline which says "Your header guard should be
MY_MODULE_H. Or FOO_MY_MODULE_H. Or if you prefer _MY_MODULE_H even if
it's wrong".

Christophe

> +
> +C++ headers and headers in new components should use // for the #endif comment.
> +The server code consistently uses /* */ for the #endif comment, keep it that way.
>  
> -Historically, some headers added underscores liberally, e.g. MY_MODULE_H_. This is neither necessary nor discouraged, although as a reminder, a leading underscore followed by a capital letter is reserved for the implementation and should not be used, so _MY_MODULE_H is, technically speaking, invalid C.
>  
>  Header inclusion
>  ----------------
> -- 
> 2.13.5 (Apple Git-94)
> 
> _______________________________________________
> Spice-devel mailing list
> Spice-devel@lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/spice-devel