Re: [libvirt] proposal: allow use of "bool": HACKING: discuss C types

"Daniel P. Berrange" <berrange(a)redhat.com&gt; wrote: ... Thanks. I've done that and will commit the following: From: Jim Meyering <meyering(a)redhat.com&gt; Date: Fri, 12 Dec 2008 09:45:31 +0100 Subject: [PATCH] HACKING: mention bool and other scalar types, const-correctness --- HACKING | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 files changed, 53 insertions(+), 0 deletions(-) diff --git a/HACKING b/HACKING index e088da8..ba03604 100644 --- a/HACKING +++ b/HACKING @@ -91,6 +91,59 @@ Usually they're in macro definitions or strings, and should be converted anyhow. +C types +======= +Use the right type. + +Scalars +------- +If you're using "int" or "long", odds are good that there's a better type. +If a variable is counting something, be sure to declare it with an +unsigned type. +If it's memory-size-related, use size_t (use ssize_t only if required). +If it's file-size related, use uintmax_t, or maybe off_t. +If it's file-offset related (i.e., signed), use off_t. +If it's just counting small numbers use "unsigned int"; +(on all but oddball embedded systems, you can assume that that +type is at least four bytes wide). +If a variable has boolean semantics, give it the "bool" type +and use the corresponding "true" and "false" macros. It's ok +to include <stdbool.h>, since libvirt's use of gnulib ensures +that it exists and is usable. +In the unusual event that you require a specific width, use a +standard type like int32_t, uint32_t, uint64_t, etc. + +While using "bool" is good for readability, it comes with minor caveats: + - Don't use "bool" in places where the type size must be constant across + all systems, like public interfaces and on-the-wire protocols. + - Don't compare a bool variable against the literal, "true", + since a value with a logical non-false value need not be "1". + I.e., don't write "if (seen == true) ...". Rather, write "if (seen)...". + +Of course, take all of the above with a grain of salt. If you're about +to use some system interface that requires a type like size_t, pid_t or +off_t, use matching types for any corresponding variables. + +Also, if you try to use e.g., "unsigned int" as a type, and that +conflicts with the signedness of a related variable, sometimes +it's best just to use the *wrong* type, if "pulling the thread" +and fixing all related variables would be too invasive. + +Finally, while using descriptive types is important, be careful not to +go overboard. If whatever you're doing causes warnings, or requires +casts, then reconsider or ask for help. + +Pointers +-------- +Ensure that all of your pointers are "const-correct". +Unless a pointer is used to modify the pointed-to storage, +give it the "const" attribute. That way, the reader knows +up-front that this is a read-only pointer. Perhaps more +importantly, if we're diligent about this, when you see a non-const +pointer, you're guaranteed that it is used to modify the storage +it points to, or it is aliased to another pointer that is. + + Low level memory management =========================== -- 1.6.1.94.g9388