| Message ID | 20190812234630.22814-1-ehabkost@redhat.com (mailing list archive) |
|---|---|
| State | New, archived |
| Headers | show |
| Series | [v2] HACKING: Document 'struct' keyword usage | expand |
On 8/13/19 1:46 AM, Eduardo Habkost wrote: > Sometimes we use the 'struct' keyword in headers to help us > reduce dependencies between header files. Document that > practice. > > Signed-off-by: Paolo Bonzini <pbonzini@redhat.com> > Signed-off-by: Eduardo Habkost <ehabkost@redhat.com> > --- > Changes v1 -> v2: > * Use paragraphs written by Paolo Bonzini at > https://www.mail-archive.com/qemu-devel@nongnu.org/msg586214.html > * Fix typos spotted by Thomas Huth > --- > HACKING | 14 +++++++++++++- > 1 file changed, 13 insertions(+), 1 deletion(-) > > diff --git a/HACKING b/HACKING > index 0fc3e0fc04..035276e668 100644 > --- a/HACKING > +++ b/HACKING > @@ -100,7 +100,19 @@ pointer, you're guaranteed that it is used to modify the storage > it points to, or it is aliased to another pointer that is. > > 2.3. Typedefs > -Typedefs are used to eliminate the redundant 'struct' keyword. > + > +Typedefs are used to eliminate the redundant 'struct' keyword, since type > +names have a different style than other identifiers ("CamelCase" versus > +"snake_case"). Each struct should have a CamelCase name and a Maybe s/Each struct/Each global struct/ ? Or "non-local" or something similar? Sometimes, you also define a struct just within a function, and in that case we don't require the typedef, do we? > +corresponding typedef. > + > +Since certain C compilers choke on duplicated typedefs, you should avoid > +them and declare a typedef only in one header file. For common types, > +you can use "include/qemu/typedefs.h" for example. However, as a matter > +of convenience it is also perfectly fine to use forward struct > +definitions instead of typedefs in headers and function prototypes; this > +avoids problems with duplicated typedefs and reduces the need to include > +headers from other headers. Reviewed-by: Thomas Huth <thuth@redhat.com>
On 13/08/19 08:44, Thomas Huth wrote: > Maybe s/Each struct/Each global struct/ ? Or "non-local" or something > similar? Sometimes, you also define a struct just within a function, and > in that case we don't require the typedef, do we? I changed it to "each named struct" and queued. Thanks, Paolo
diff --git a/HACKING b/HACKING index 0fc3e0fc04..035276e668 100644 --- a/HACKING +++ b/HACKING @@ -100,7 +100,19 @@ pointer, you're guaranteed that it is used to modify the storage it points to, or it is aliased to another pointer that is. 2.3. Typedefs -Typedefs are used to eliminate the redundant 'struct' keyword. + +Typedefs are used to eliminate the redundant 'struct' keyword, since type +names have a different style than other identifiers ("CamelCase" versus +"snake_case"). Each struct should have a CamelCase name and a +corresponding typedef. + +Since certain C compilers choke on duplicated typedefs, you should avoid +them and declare a typedef only in one header file. For common types, +you can use "include/qemu/typedefs.h" for example. However, as a matter +of convenience it is also perfectly fine to use forward struct +definitions instead of typedefs in headers and function prototypes; this +avoids problems with duplicated typedefs and reduces the need to include +headers from other headers. 2.4. Reserved namespaces in C and POSIX Underscore capital, double underscore, and underscore 't' suffixes should be