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

[Jim Meyering]

"Daniel P. Berrange" <berrange at redhat.com> wrote:
...
> Ok, if you want to re-post the HACKING file also mentioning that
> 'bool' shouldn't be used in our public APIs & wire protocol,
> and that 'true' / 'false' should only be used for initialization
> I'm fine with the rest of the docs.

Thanks.
I've done that and will commit the following:

>From 6abb25e9a40221dd299b6a136c4f4046fa2f5529 Mon Sep 17 00:00:00 2001
From: Jim Meyering <meyering at redhat.com>
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