GNOME Bugzilla – Bug 748216
GNOME Programming Guidelines contain advice that go against the C standard
Last modified: 2015-04-21 09:06:22 UTC
The GNOME Programming Guidelines, and specifically the recommended C Coding Conventions [1] contain several advice that go against the C standard. I know these are commonplace, and have been used with no harm, but there's no reason to do things the wrong way when there are other viable alternatives. As an example: - The recommended include guards are in the form: __MODULE_FILE_H__ Some alternatives: MODULE_FILE_H, MODULE_FILE_H_, MODULE_FILE_H_INCLUDED_,... - The recommended way to declare a GObject is: typedef struct _FooBar FooBar; This convention is also used by the G_DECLARE_* macros. An alternative would be "typedef struct FooBar_ FooBar" or, since typedefs and structs are on different namespaces, "typedef struct FooBar FooBar". [1] https://developer.gnome.org/programming-guidelines/unstable/c-coding-style.html.en [2] http://c-faq.com/decl/namespace.html
(In reply to Alex Puchades from comment #0) > The GNOME Programming Guidelines, and specifically the recommended C Coding > Conventions [1] contain several advice that go against the C standard. I > know these are commonplace, and have been used with no harm, but there's no > reason to do things the wrong way when there are other viable alternatives. > > As an example: > > - The recommended include guards are in the form: __MODULE_FILE_H__ > Some alternatives: MODULE_FILE_H, MODULE_FILE_H_, > MODULE_FILE_H_INCLUDED_,... An easy fix, so I made that change as commit 91a113c25495925f87533cdafdfd49ce9a2b5aa7. > - The recommended way to declare a GObject is: typedef struct _FooBar > FooBar; This convention is also used by the G_DECLARE_* macros. > An alternative would be "typedef struct FooBar_ FooBar" or, since typedefs > and structs are on different namespaces, "typedef struct FooBar FooBar". As this convention is part of the GObject API, it is unlikely to change.
(In reply to David King from comment #1) > (In reply to Alex Puchades from comment #0) > > The GNOME Programming Guidelines, and specifically the recommended C Coding > > Conventions [1] contain several advice that go against the C standard. I > > know these are commonplace, and have been used with no harm, but there's no > > reason to do things the wrong way when there are other viable alternatives. > > > > As an example: > > > > - The recommended include guards are in the form: __MODULE_FILE_H__ > > Some alternatives: MODULE_FILE_H, MODULE_FILE_H_, > > MODULE_FILE_H_INCLUDED_,... > > An easy fix, so I made that change as commit > 91a113c25495925f87533cdafdfd49ce9a2b5aa7. Thanks for the quick fix. > > - The recommended way to declare a GObject is: typedef struct _FooBar > > FooBar; This convention is also used by the G_DECLARE_* macros. > > An alternative would be "typedef struct FooBar_ FooBar" or, since typedefs > > and structs are on different namespaces, "typedef struct FooBar FooBar". > > As this convention is part of the GObject API, it is unlikely to change. Fair enough. However, I'd like to add that the possibility that this change alone would cause any code to fail is very unlikely: - Since this change would only affect the documentation, old code can stay the same. - As long as there's no code (read: macros) relying on this illegal convention (and they should really be using the typedefs anyway), old and new code can coexist. - Old code can be corrected, and avoiding breakage is very easy. Glib macros can be corrected sometime in the future, as long as there's no code relying on the current behaviour. Although unlikely, if this kind of breakage is undesirable, I think it should be introduced in a posterior glib version. Until the gnome-devel-docs are fully corrected, I think we shouldn't consider this bug fixed. [1] https://developer.gnome.org/gobject/stable/gtype-instantiable-classed.html
(In reply to Alex Puchades from comment #2) > (In reply to David King from comment #1) > > > - The recommended way to declare a GObject is: typedef struct _FooBar > > > FooBar; This convention is also used by the G_DECLARE_* macros. > > > An alternative would be "typedef struct FooBar_ FooBar" or, since typedefs > > > and structs are on different namespaces, "typedef struct FooBar FooBar". > > > > As this convention is part of the GObject API, it is unlikely to change. *snip* > Glib macros can be corrected sometime in the future, as long as there's no > code relying on the current behaviour. Although unlikely, if this kind of > breakage is undesirable, I think it should be introduced in a posterior glib > version. Until the gnome-devel-docs are fully corrected, I think we > shouldn't consider this bug fixed. I would say it’s important for the docs to match how GLib works, so if you feel strongly about this, please file a bug against GLib to change the implementation of G_DECLARE_* (and to also change the GLib documentation, if necessary). Once that’s done, this bug can be reopened and changes pushed.