HACKING: mention bool and other scalar types, const-correctness

This commit is contained in:
Jim Meyering 2009-01-05 08:12:11 +00:00
parent 13a223253c
commit 33a7dc93d8
2 changed files with 57 additions and 0 deletions

View File

@ -1,3 +1,7 @@
Mon Jan 5 09:11:21 CET 2009 Jim Meyering <meyering@redhat.com>
HACKING: mention bool and other scalar types, const-correctness
Fri Dec 26 14:22:04 CET 2008 Guido Günther <agx@sigxcpu.org> Fri Dec 26 14:22:04 CET 2008 Guido Günther <agx@sigxcpu.org>
document vnc's keymap attribute document vnc's keymap attribute

53
HACKING
View File

@ -91,6 +91,59 @@ Usually they're in macro definitions or strings, and should be converted
anyhow. 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 Low level memory management
=========================== ===========================