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

[Lukáš Hrázký]

On Wed, 2018-02-14 at 22:43 +0100, Christophe de Dinechin wrote:
> > 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.

FWIW, I see no reason to use /* */ when // is simpler.

Lukas

> > ----
> > 
> > -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
> 
> _______________________________________________
> Spice-devel mailing list
> Spice-devel at lists.freedesktop.org
> https://lists.freedesktop.org/mailman/listinfo/spice-devel