Here are some coding style guidelines for the Deadwood code base:
* Use the dw_str library for all string operations. This protects
us from buffer overflows.
* Functions that create a string object should have an error catcher at
the end that destroys any strings created inside the function. *Do not*
use "return foo;" in a function with an error cather, instead use
"ret = foo; goto catch_function_name;". This ensures that any allocated
strings are destroyed.
There are certain cases where the string destructor is not so simple. For
example, a string may be declared in one function, and allocated in another
function called by the first function. If this is done, when the
string is allocated in the sub-function, make a note of where the
destructor for the string is, and make sure the string is destroyed.
I understand that goto is considered bad style in some circles. It is
necessary here to make up for C's lack of error catching (if only C had
try/catch/throw).
* Whenever a string is to be destroyed, make sure the string has a non-0
value. Once a string is destoryed, set the string to have a 0 value.
This stops double-free()s and freeing of null pointers.
* Any indexed writes, such as a[b] = c or *(a + b) = c need to have
some kind of bounds checking. This protects us from buffer overflows.
* Arrays and strings should always be at least one character longer than
you think you will need for the array. This protects us from off-by-one
errors.
* Any resource created: File pointers, sockets, etc. needs a destructor.
File pointers are usually destroyed after reading the file, or if there
is an error reading a file. Sockets are destroyed after using the
socket (or never in case of the sockets that bind to ports). Etc.
* A single function should not, unless there is a compelling reason, be
longer than 52 lines. The thinking is this: If we keep individual
functions small, then the code will be easier to follow and debug.
Should a function be 52 lines or longer, please state why in the comments
before the function. The size of a function does not include any comments
before the function describing the function.
(When finishing up the recursion, I started ignoring this particular
rule. Functions are still fairly short and should be easy to follow.)
* All functions should be documented with at least a brief comment. If you
are not a native English speaker, please let me know, and I will correct
any grammatical errors in your comments.
* Code should be written using an environment where each tab stop is eight
spaces long. A single line of code should never be wider than 80 columns
(yes, this is a throwback to ancient history when there existed text
terminals with 80 columns per line). If you find yourself nesting more
deeply, consider putting the deeply nested code in a sub-function.
* All variables should be decalred at the beginning of a function. All
variables should have some initial value, usually 0. This is not true for
all variable types; complicated structures do not need to be initialized
in the variable declaration at the top. However, all integers and pointers
must be initalized; pointers must be initialized with a value of 0.
* Complicated data structures should be initialized with either a small
function, or a #define init_structure(a) a.element1 = 0; a.element2=0;
form. This way, if we add a new element to the structure, we only need
to change the one initalizer.
* All "for"s, "if"s, "while"s, etc. should use bracing, even if we are
only looking at one statement.
* condition ? true : false constructs should not be used unless there is
a compelling reason to use them. Please state the compelling reason to
use the x?t:f form in the comments around the code in question.
* When using code that needs an integer with a given size, it is best to
use the C99 forms supported in the <stdint.h> header file:
uint8_t for unsigned 8-bit numbers
int8_t for signed 8-bit numbers
uint16_t for unsigned 16-bit numbers
int16_t for signed 16-bit numbers
uint32_t for unsigned 32-bit numbers
int32_t for signed 32-bit numbers
uint64_t for unsigned 64-bit numbers
int64_t for signed 64-bit numbers
* Likewise, an "int" without a size specified should still work if a given
compiler's "int" is a 16-bit number (-32768 to 32767)
* malloc() system calls (and dw_new() calls) must have their return value
checked. If the return value is 0, do something appropriate, like telling
the user the program could not allocate memory and exiting.
* All code that uses sockets needs to be written in a manner that works in
both Windows and *NIX. See the SOCKET.CODING.STYLE document for all
of the details.
* All variables used inside a function must be declared at the beginning
of the function. Since we have a "functions are 52 lines or shorter"
rule, this should not be too difficult to do. The reason for this:
It makes code audits easier.
* All code needs to be written in an endian-neutral manner. For example,
instead of:
uint16_t foo;
foo = (uint16_t *)(some_string);
Use something like:
uint16_t foo;
if(some_string_size + 1 > some_string_maximum_size) {
ret = -1;
goto catch_this_functions_name;
}
foo = (*(some_string + 1) & 0xff) | ((*some_string & 0xff00) >> 16);
* Bracing looks like this:
int foo() {
int a = 0;
for(a = 0; a < 100; a++) {
if(a < 50) {
printf("A is only %d\n",a);
} else if(a < 75) {
printf("A is %d\n",a);
} else {
printf("A is now %d\n",a);
}
}
}
* #ifdef and other conditional compiling macros must, in the corresponding
#endif, have, in comments, the name of the "define" needed to compile the
code in question. For example:
#ifdef FOO
foo_bug_workaround();
#endif /* FOO */
* There are not to be potential infinite loops. while(1) and for(;;)
constructs are not allowed, unless it is the program's main loop.
In DwSocket.c and DwTcpSocket.c, the for(;;) is the program's main loop
while(1) constructs are not used; always use for(;;) for the program's main
loop
while loops must be written in such a way that a counter increments and
the while loop will eventually terminate if the counter goes over a
reasonable value.
This is to stop bugs like the bug that caused some Microsoft Zunes to
freeze on December 31, 2008
