From 33a7dc93d88f7f1ba0fb2e4f8d2efab128e21837 Mon Sep 17 00:00:00 2001 From: Jim Meyering Date: Mon, 5 Jan 2009 08:12:11 +0000 Subject: [PATCH] HACKING: mention bool and other scalar types, const-correctness --- ChangeLog | 4 ++++ HACKING | 53 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 57 insertions(+) diff --git a/ChangeLog b/ChangeLog index 0d4994e85e..a23cfac3d5 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,7 @@ +Mon Jan 5 09:11:21 CET 2009 Jim Meyering + + HACKING: mention bool and other scalar types, const-correctness + Fri Dec 26 14:22:04 CET 2008 Guido Günther document vnc's keymap attribute diff --git a/HACKING b/HACKING index e088da8628..ba036043ea 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 , 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 =========================== -- GitLab