[Spice-devel] [spice-server] style: Slight tweak to the header guard section

[Christophe de Dinechin]

> On 14 Feb 2018, at 17:29, Christophe Fergeau <cfergeau at redhat.com> wrote:
> 
> This changes the suggested style to what is currently used in
> spice-server codebase. This also removes a few sentences which
> are not really related to how one should format their header guards.
> 
> Signed-off-by: Christophe Fergeau <cfergeau at redhat.com>
> ---
> docs/spice_style.txt | 6 ++----
> 1 file changed, 2 insertions(+), 4 deletions(-)
> 
> diff --git a/docs/spice_style.txt b/docs/spice_style.txt
> index c8a4cff66..bc18b1d9e 100644
> --- a/docs/spice_style.txt
> +++ b/docs/spice_style.txt
> @@ -365,12 +365,10 @@ Headers should be protected against multiple inclusion using a macro that contai
> 
> ...
> 
> -#endif // MY_MODULE_H
> +#endif /* MY_MODULE_H */

I had first written it with C style, Frediano suggested C++ style.Both are OK. Currently, we have 44 of one and 208 of the other, so the existing code base does not imply one or the other.

> ----
> 
> -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.

Nack the removal. We want a guideline, because right now it’s “anything goes” and it looks ugly:

channel-smartcard.h:18:#ifndef __SPICE_CLIENT_SMARTCARD_CHANNEL_H__ (not a legal name)
channel-display-priv.h:18:#ifndef CHANNEL_DISPLAY_PRIV_H_
spice-widget-priv.h:18:#ifndef __SPICE_WIDGET_PRIV_H__
usb-acl-helper.h:21:#ifndef __SPICE_USB_ACL_HELPER_H__
channel-usbredir-priv.h:21:#ifndef __SPICE_CLIENT_USBREDIR_CHANNEL_PRIV_H__
generated_client_marshallers.h:23:#ifndef _H_GENERATED_CLIENT_MARSHALLERS
spice-char.h:18:#ifndef SPICE_CHAR_H_
net-utils.h:18:#ifndef RED_NET_UTILS_H_
hexdump.h:6:#ifndef RH_STREAMING_AGENT_HEXDUMP_H_


> -
> -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.

Nack the removal, see example of channel-smartcard.h, which is not legal, it’s reserved to the implementation, i.e. compiler and standard libraries.

17.4.3.1.2 Global names [lib.global.names]

Certain sets of names and function signatures are always reserved to the implementation:

	• Each name that contains a double underscore (__) or begins with an underscore followed by an uppercase letter (2.11) is reserved to the implementation for any use.
	• Each name that begins with an underscore is reserved to the implementation for use as a name in the global namespace.165


> +C++ headers would use C++ comments.

There are no “C++ comments” anymore since C99.

> 
> Header inclusion
> ----------------
> -- 
> 2.14.3
> 
> _______________________________________________
> Spice-devel mailing list
> Spice-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/spice-devel