HACKING: Document 'struct' keyword usage
PATCH v2 1/1 HACKING: Document 'struct' keyword usage
Sometimes we use the 'struct' keyword in headers to help us reduce dependencies between header files. Document that practice.
---
Changes v1 -> v2:
* Use paragraphs written by Paolo Bonzini at
https://www.mail-archive.com/[email protected]/msg586214.html
* Fix typos spotted by Thomas Huth
--- HACKING | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-)
HACKING +13 -1
@@ -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
Signature · 1 line
2.21.0
Quoted 20 lines · Eduardo Habkost
Sometimes we use the 'struct' keyword in headers to help us reduce dependencies between header files. Document that practice.
Signed-off-by Paolo Bonzini <[email protected]>Signed-off-by Eduardo Habkost <[email protected]>---
Changes v1 -> v2:
* Use paragraphs written by Paolo Bonzini at
https://www.mail-archive.com/[email protected]/msg586214.html
* Fix typos spotted by Thomas Huth--- HACKING | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-)HACKING +0
-0
HACKING pointer, you're guaranteed that it is used to modify the storage · line 106
Quoted 8 lines
HACKING +4
-1@@ -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?
HACKING pointer, you're guaranteed that it is used to modify the storage · line 115
Quoted 9 lines
HACKING +9
-0+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.
Quoted 3 lines · Thomas Huth
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