nutcracker 0.2.3

data/ext/nutcracker/m4/ltversion.m4

@@ -0,0 +1,23 @@
+# ltversion.m4 -- version numbers			-*- Autoconf -*-
+#
+#   Copyright (C) 2004 Free Software Foundation, Inc.
+#   Written by Scott James Remnant, 2004
+#
+# This file is free software; the Free Software Foundation gives
+# unlimited permission to copy and/or distribute it, with or without
+# modifications, as long as this notice is preserved.
+
+# Generated from ltversion.in.
+
+# serial 3012 ltversion.m4
+# This file is part of GNU Libtool
+
+m4_define([LT_PACKAGE_VERSION], [2.2.6])
+m4_define([LT_PACKAGE_REVISION], [1.3012])
+
+AC_DEFUN([LTVERSION_VERSION],
+[macro_version='2.2.6'
+macro_revision='1.3012'
+_LT_DECL(, macro_version, 0, [Which release of libtool.m4 was used?])
+_LT_DECL(, macro_revision, 0)
+])

data/ext/nutcracker/m4/lt~obsolete.m4

@@ -0,0 +1,92 @@
+# lt~obsolete.m4 -- aclocal satisfying obsolete definitions.    -*-Autoconf-*-
+#
+#   Copyright (C) 2004, 2005, 2007 Free Software Foundation, Inc.
+#   Written by Scott James Remnant, 2004.
+#
+# This file is free software; the Free Software Foundation gives
+# unlimited permission to copy and/or distribute it, with or without
+# modifications, as long as this notice is preserved.
+
+# serial 4 lt~obsolete.m4
+
+# These exist entirely to fool aclocal when bootstrapping libtool.
+#
+# In the past libtool.m4 has provided macros via AC_DEFUN (or AU_DEFUN)
+# which have later been changed to m4_define as they aren't part of the
+# exported API, or moved to Autoconf or Automake where they belong.
+#
+# The trouble is, aclocal is a bit thick.  It'll see the old AC_DEFUN
+# in /usr/share/aclocal/libtool.m4 and remember it, then when it sees us
+# using a macro with the same name in our local m4/libtool.m4 it'll
+# pull the old libtool.m4 in (it doesn't see our shiny new m4_define
+# and doesn't know about Autoconf macros at all.)
+#
+# So we provide this file, which has a silly filename so it's always
+# included after everything else.  This provides aclocal with the
+# AC_DEFUNs it wants, but when m4 processes it, it doesn't do anything
+# because those macros already exist, or will be overwritten later.
+# We use AC_DEFUN over AU_DEFUN for compatibility with aclocal-1.6. 
+#
+# Anytime we withdraw an AC_DEFUN or AU_DEFUN, remember to add it here.
+# Yes, that means every name once taken will need to remain here until
+# we give up compatibility with versions before 1.7, at which point
+# we need to keep only those names which we still refer to.
+
+# This is to help aclocal find these macros, as it can't see m4_define.
+AC_DEFUN([LTOBSOLETE_VERSION], [m4_if([1])])
+
+m4_ifndef([AC_LIBTOOL_LINKER_OPTION],	[AC_DEFUN([AC_LIBTOOL_LINKER_OPTION])])
+m4_ifndef([AC_PROG_EGREP],		[AC_DEFUN([AC_PROG_EGREP])])
+m4_ifndef([_LT_AC_PROG_ECHO_BACKSLASH],	[AC_DEFUN([_LT_AC_PROG_ECHO_BACKSLASH])])
+m4_ifndef([_LT_AC_SHELL_INIT],		[AC_DEFUN([_LT_AC_SHELL_INIT])])
+m4_ifndef([_LT_AC_SYS_LIBPATH_AIX],	[AC_DEFUN([_LT_AC_SYS_LIBPATH_AIX])])
+m4_ifndef([_LT_PROG_LTMAIN],		[AC_DEFUN([_LT_PROG_LTMAIN])])
+m4_ifndef([_LT_AC_TAGVAR],		[AC_DEFUN([_LT_AC_TAGVAR])])
+m4_ifndef([AC_LTDL_ENABLE_INSTALL],	[AC_DEFUN([AC_LTDL_ENABLE_INSTALL])])
+m4_ifndef([AC_LTDL_PREOPEN],		[AC_DEFUN([AC_LTDL_PREOPEN])])
+m4_ifndef([_LT_AC_SYS_COMPILER],	[AC_DEFUN([_LT_AC_SYS_COMPILER])])
+m4_ifndef([_LT_AC_LOCK],		[AC_DEFUN([_LT_AC_LOCK])])
+m4_ifndef([AC_LIBTOOL_SYS_OLD_ARCHIVE],	[AC_DEFUN([AC_LIBTOOL_SYS_OLD_ARCHIVE])])
+m4_ifndef([_LT_AC_TRY_DLOPEN_SELF],	[AC_DEFUN([_LT_AC_TRY_DLOPEN_SELF])])
+m4_ifndef([AC_LIBTOOL_PROG_CC_C_O],	[AC_DEFUN([AC_LIBTOOL_PROG_CC_C_O])])
+m4_ifndef([AC_LIBTOOL_SYS_HARD_LINK_LOCKS], [AC_DEFUN([AC_LIBTOOL_SYS_HARD_LINK_LOCKS])])
+m4_ifndef([AC_LIBTOOL_OBJDIR],		[AC_DEFUN([AC_LIBTOOL_OBJDIR])])
+m4_ifndef([AC_LTDL_OBJDIR],		[AC_DEFUN([AC_LTDL_OBJDIR])])
+m4_ifndef([AC_LIBTOOL_PROG_LD_HARDCODE_LIBPATH], [AC_DEFUN([AC_LIBTOOL_PROG_LD_HARDCODE_LIBPATH])])
+m4_ifndef([AC_LIBTOOL_SYS_LIB_STRIP],	[AC_DEFUN([AC_LIBTOOL_SYS_LIB_STRIP])])
+m4_ifndef([AC_PATH_MAGIC],		[AC_DEFUN([AC_PATH_MAGIC])])
+m4_ifndef([AC_PROG_LD_GNU],		[AC_DEFUN([AC_PROG_LD_GNU])])
+m4_ifndef([AC_PROG_LD_RELOAD_FLAG],	[AC_DEFUN([AC_PROG_LD_RELOAD_FLAG])])
+m4_ifndef([AC_DEPLIBS_CHECK_METHOD],	[AC_DEFUN([AC_DEPLIBS_CHECK_METHOD])])
+m4_ifndef([AC_LIBTOOL_PROG_COMPILER_NO_RTTI], [AC_DEFUN([AC_LIBTOOL_PROG_COMPILER_NO_RTTI])])
+m4_ifndef([AC_LIBTOOL_SYS_GLOBAL_SYMBOL_PIPE], [AC_DEFUN([AC_LIBTOOL_SYS_GLOBAL_SYMBOL_PIPE])])
+m4_ifndef([AC_LIBTOOL_PROG_COMPILER_PIC], [AC_DEFUN([AC_LIBTOOL_PROG_COMPILER_PIC])])
+m4_ifndef([AC_LIBTOOL_PROG_LD_SHLIBS],	[AC_DEFUN([AC_LIBTOOL_PROG_LD_SHLIBS])])
+m4_ifndef([AC_LIBTOOL_POSTDEP_PREDEP],	[AC_DEFUN([AC_LIBTOOL_POSTDEP_PREDEP])])
+m4_ifndef([LT_AC_PROG_EGREP],		[AC_DEFUN([LT_AC_PROG_EGREP])])
+m4_ifndef([LT_AC_PROG_SED],		[AC_DEFUN([LT_AC_PROG_SED])])
+m4_ifndef([_LT_CC_BASENAME],		[AC_DEFUN([_LT_CC_BASENAME])])
+m4_ifndef([_LT_COMPILER_BOILERPLATE],	[AC_DEFUN([_LT_COMPILER_BOILERPLATE])])
+m4_ifndef([_LT_LINKER_BOILERPLATE],	[AC_DEFUN([_LT_LINKER_BOILERPLATE])])
+m4_ifndef([_AC_PROG_LIBTOOL],		[AC_DEFUN([_AC_PROG_LIBTOOL])])
+m4_ifndef([AC_LIBTOOL_SETUP],		[AC_DEFUN([AC_LIBTOOL_SETUP])])
+m4_ifndef([_LT_AC_CHECK_DLFCN],		[AC_DEFUN([_LT_AC_CHECK_DLFCN])])
+m4_ifndef([AC_LIBTOOL_SYS_DYNAMIC_LINKER],	[AC_DEFUN([AC_LIBTOOL_SYS_DYNAMIC_LINKER])])
+m4_ifndef([_LT_AC_TAGCONFIG],		[AC_DEFUN([_LT_AC_TAGCONFIG])])
+m4_ifndef([AC_DISABLE_FAST_INSTALL],	[AC_DEFUN([AC_DISABLE_FAST_INSTALL])])
+m4_ifndef([_LT_AC_LANG_CXX],		[AC_DEFUN([_LT_AC_LANG_CXX])])
+m4_ifndef([_LT_AC_LANG_F77],		[AC_DEFUN([_LT_AC_LANG_F77])])
+m4_ifndef([_LT_AC_LANG_GCJ],		[AC_DEFUN([_LT_AC_LANG_GCJ])])
+m4_ifndef([AC_LIBTOOL_RC],		[AC_DEFUN([AC_LIBTOOL_RC])])
+m4_ifndef([AC_LIBTOOL_LANG_C_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_C_CONFIG])])
+m4_ifndef([_LT_AC_LANG_C_CONFIG],	[AC_DEFUN([_LT_AC_LANG_C_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_CXX_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_CXX_CONFIG])])
+m4_ifndef([_LT_AC_LANG_CXX_CONFIG],	[AC_DEFUN([_LT_AC_LANG_CXX_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_F77_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_F77_CONFIG])])
+m4_ifndef([_LT_AC_LANG_F77_CONFIG],	[AC_DEFUN([_LT_AC_LANG_F77_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_GCJ_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_GCJ_CONFIG])])
+m4_ifndef([_LT_AC_LANG_GCJ_CONFIG],	[AC_DEFUN([_LT_AC_LANG_GCJ_CONFIG])])
+m4_ifndef([AC_LIBTOOL_LANG_RC_CONFIG],	[AC_DEFUN([AC_LIBTOOL_LANG_RC_CONFIG])])
+m4_ifndef([_LT_AC_LANG_RC_CONFIG],	[AC_DEFUN([_LT_AC_LANG_RC_CONFIG])])
+m4_ifndef([AC_LIBTOOL_CONFIG],		[AC_DEFUN([AC_LIBTOOL_CONFIG])])
+m4_ifndef([_LT_AC_FILE_LTDLL_C],	[AC_DEFUN([_LT_AC_FILE_LTDLL_C])])

data/ext/nutcracker/notes/c-styleguide.txt

@@ -0,0 +1,425 @@
+- No literal tabs. Expand tabs to 4 spaces.
+- Indentation is 4 spaces.
+- No more than 3 levels of indentation, otherwise you should think about
+  refactoring your code.
+- Use one statement per line.
+- Make sure that your editor does not leave space at the end of the line.
+- snake_case for variable, function and file names.
+- Use your own judgment when naming variables and functions. Be as Spartan
+  as possible. Eg: Using name like this_variable_is_a_temporary_counter
+  will usually be frowned upon.
+- Don’t use local variables or parameters that shadow global identifiers.
+  GCC’s ‘-Wshadow’ option can help you to detect this problem.
+
+- Avoid using int, char, short, long. Instead use int8_t uint8_t, int16_t,
+  uint16_t, int32_t, uint32_t, int64_t, uint64_t, which are available in
+  <stdint.h>. However, when interfacing with system calls and libraries
+  you cannot get away from using int and char.
+- Use bool for boolean variables. You have to include <stdbool.h>
+- Avoid using a bool as type for struct member names. Instead use unsigned
+  1-bit bit field. Eg:
+  struct foo {
+      unsigned is_bar:1;
+  };
+- Always use size_t type when dealing with sizes of objects or memory ranges.
+- Your code should be 64-bit and 32-bit friendly. Bear in mind problems
+  of printing, comparisons, and structure alignment. You have to include
+  <intyptes.h> to get generic format specifier macros for printing.
+
+- 80 column line limit.
+- If you have to wrap a long statement (> 80 column), put the operator at the
+  end of the line and indent the next line at the same column as the arguments
+  in the previous column. Eg:
+    while (cnt < 20 && this_variable_name_is_too_long &&
+           ep != NULL) {
+        z = a + really + long + statement + that + needs + three + lines +
+            gets + indented + on + the + same + column + as + the +
+            previous + column
+    }
+
+    and:
+
+    int a = function(param_a, param_b, param_c, param_d, param_e, param_f,
+                     param_g, param_h, param_i, param_j, param_k, param_l);
+
+- Always use braces for all conditional blocks (if, switch, for, while, do).
+  This holds good even for single statement conditional blocks. Eg:
+    if (cond) {
+        stmt;
+    }
+- Placement of braces for non-function statement blocks - put opening brace
+  last on the line and closing brace first. Eg:
+    if (x is true) {
+        we do y
+    }
+- Placement of brace for functions - put the opening brace at the beginning
+  of the next line and closing brace first. This is useful because several
+  tools look for opening brace in column one to find beginning of C
+  functions. Eg:
+int
+function(int x)
+{
+    body of the function
+}
+
+- Closing brace is empty on a line of its own, except in cases where it is
+  followed by a continuation of the same statement, i.e. a "while" in a
+  do-statement or an "else" in an if-statement, like this:
+    do {
+        body of do-loop
+    } while (condition);
+
+    and,
+
+    if (x == y) {
+        ..
+    } else if (x > y) {
+        ...
+    } else {
+        ....
+    }
+
+- Column align switch keyword and the corresponding case/default keyword. Eg:
+    switch (alphabet) {
+    case 'a':
+    case 'b':
+        printf("I am a or b\n");
+        break;
+
+    default:
+        break;
+    }
+
+- Forever loops are done with for, and not while. Eg:
+    for (;;) {
+        stmt;
+    }
+
+- Don't use a space after a function name.
+- Do not needlessly surround the return expression with parentheses.
+- Use space after keywords. Exceptions are sizeof, typeof, alignof and
+  __attribute__, which look like functions.
+- Do not add spaces around (inside) parenthesized expressions.
+    s = sizeof( sizeof(*p)) ); /* bad example */
+    s = sizeof(sizeof(*p));    /* good example */
+- Casts should not be followed by space. Eg:
+  int q = *(int *)&p
+- There is no need to type cast when assigning a void pointer to a non-void
+  pointer, or vice versa.
+- Avoid using goto statements. However there are some exceptions to this rule
+  when a single goto label within a function and one or more goto statements
+  come in handy when a function exits from multiple locations and some common
+  work such as cleanup has to be done. Eg:
+int
+fun(void)
+{
+    int result = 0;
+    char *buffer;
+
+    buffer = malloc(1024);
+    if (buffer == NULL) {
+        return -1;
+    }
+
+    if (condition1) {
+        while (loop1) {
+            ...
+        }
+        result = 1;
+        goto out;
+    }
+
+    ...
+out:
+    free(buffer);
+    return result;
+}
+- When declaring pointer data, use '*' adjacent to the data name and not
+  adjacent to the type name. Eg:
+    int
+    function(int *p)
+    {
+        char *p;
+        <body of the function>
+    }
+- Use one space around (on each side of) most binary and ternary operators,
+  such as any of these:
+    =  +  -  <  >  *  /  %  |  &  ^  <=  >=  ==  !=  ?  :
+  but no space after unary operators:
+    &  *  +  -  ~  !  sizeof typeof alignof  __attribute__  defined
+  no space before the postfix increment & decrement unary operators:
+    ++  --
+  and no space around the '.' and "->" structure member operators.
+
+- 0 and NULL; use 0 for integers, 0.0 for doubles, NULL for pointers, and
+  '\0' for chars.
+- Test pointers against NULL. E.g, use:
+    if (p == NULL)
+
+    not:
+
+    !(p)
+
+- Do not use ! for tests unless it is a boolean. E.g. use:
+    if (*p == '\0')
+
+    not:
+
+    if (!*p)
+
+- Don't use assignments inside if or while-conditions. E.g, use:
+
+    struct foo *foo;
+    foo = malloc(sizeof(*foo));
+    if (foo == NULL) {
+        return -1
+    }
+
+    not:
+
+    struct foo *foo;
+    if ((foo = malloc(sizeof(*foo))) == NULL) {
+        return -1;
+    }
+
+- Don't ever use typedef for structure types. Typedefs are problematic
+  because they do not properly hide their underlying type; for example you
+  need to know if the typedef is the structure itself or a pointer to the
+  structure. In addition they must be declared exactly once, whereas an
+  incomplete structure type can be mentioned as many times as necessary.
+  Typedefs are difficult to use in stand-alone header files: the header
+  that defines the typedef must be included before the header that uses it,
+  or by the header that uses it (which causes namespace pollution), or
+  there must be a back-door mechanism for obtaining the typedef.
+- The only exception for using a typedef is when you are defining a type
+  for a function pointer or a type for an enum. Eg:
+
+  typedef void (*foo_handler_t)(int, void *);
+
+  or:
+
+  typedef enum types {
+      TYPE_1,
+      TYPE_2
+  } types_t;
+
+- Use just one variable declaration per line when variables are part of a
+  struct. This leaves you room for a small comment on each item, explaining
+  its use. Declarations should also be aligned. Eg, use:
+
+  struct foo {
+    int      *foo_a;   /* comment for foo_a */
+    int      foo_b;    /* comment for foo_b */
+    unsigned foo_c:1;  /* comment for foo_c */
+  };
+
+  and not:
+
+  struct foo {
+    int *foo_a, foo_b;
+    unsigned foo_c:1;
+  };
+
+- For variable declaration outside a struct, either collect all the
+  declarations of the same type on a single line, or use one variable
+  per line if the variables purpose needs to be commented. Eg:
+  char *a, *b, c;
+
+  or:
+
+  char *a, *b;
+  char c;       /* comments for c */
+
+- Avoid magic numbers because no-one has a clue (including the author) of
+  what it means after a month.
+
+- Function definitions should start the name of the function in column
+  one. This is useful because it makes searching for function definitions
+  fairly trivial. Eg:
+static char *
+concat(char *s1, char *s2)
+{
+  body of the function
+}
+
+- Function and variables local to a file should be static.
+- Separate two successive functions with one blank line.
+- Include parameter names with their datypes in function declaration. Eg:
+void function(int param);
+
+- Functions should be short and sweet, and do just one thing. They should
+  fit on one or two screenfuls of text (80 x 24 screen size), and do one
+  thing and do that well.
+  The maximum length of a function is inversely proportional to the
+  complexity and indentation level of that function. So, if you have a
+  conceptually simple function that is just one long (but simple)
+  case-statement, where you have to do lots of small things for a lot of
+  different cases, it's OK to have a longer function.
+  Another measure of the function is the number of local variables. They
+  shouldn't exceed 5-10, or you're doing something wrong. Re-think the
+  function, and split it into smaller pieces. A human brain can
+  generally easily keep track of about 7 different things, anything more
+  and it gets confused. You know you're brilliant, but maybe you'd like
+  to understand what you did 2 weeks from now.
+- Use const for function parameters passed by reference, if the passed
+  pointer has no side effect.
+
+- C style comments only. Don't use // for single line comments. Instead
+  use /* ... */ style.
+- For multi-line comments use the following style
+    /*
+     * This is the preferred style for multi-line
+     * comments in the Linux kernel source code.
+     * Please use it consistently.
+     *
+     * Description:  A column of asterisks on the left side,
+     * with beginning and ending almost-blank lines.
+     */
+
+- To comment out block of code spanning several lines use preprocessor
+  directive "#ifdef 0 ... #endif"
+
+- Please write a brief comment at the start of each source file, with the
+  file name and a line or two about the overall purpose of the file.
+
+- All major functions should have comments describing what they do at the
+  head of the function. Avoid putting comments in the function body unless
+  absolutely needed. If possible, add a comment on what sorts of arguments
+  the function gets, and what the possible values of arguments mean and
+  what they are used for and the significance of return value if there is
+  one. It is not necessary to duplicate in words the meaning of the C
+  argument declarations, if a C type is being used in its customary fashion.
+  If there is anything nonstandard about its use (such as an argument of
+  type char * which is really the address of the second character of a
+  string, not the first), or any possible values that would not work the
+  way one would expect (such as, that strings containing newlines are not
+  guaranteed to work), be sure to say so. Eg:
+
+/*
+ * Try to acquire a physical address lock while a pmap is locked. If we
+ * fail to trylock we unlock and lock the pmap directly and cache the
+ * locked pa in *locked. The caller should then restart their loop in case
+ * the virtual to physical mapping has changed.
+ *
+ * Returns 0 on success and -1 on failure.
+ */
+int
+vm_page_pa_tryrelock(pmap_t pmap, vm_paddr_t pa, vm_paddr_t *locked)
+{
+    ...
+
+- The comment on a function is much clearer if you use the argument names
+  to speak about the argument values. The variable name itself should be
+  lower case, but write it in upper case when you are speaking about the
+  value rather than the variable itself. Thus, “the inode number NODE_NUM”
+  rather than “an inode”.
+
+- Every struct definition should have an accompanying comment that
+  describes what it is for and how it should be used.
+
+- Finally, while comments are absolutely important to keep the code readable,
+  remember that the best code is self-documenting. Giving sensible names to
+  types and variables is much better than using obscure names that you must
+  then explain through comments.
+
+- Recommend using UPPERCASE for macro names. However, sometimes using
+  lowercase for macro names makes sense when macros masquerade as well-known
+  function calls. Eg, it makes sense to write the wrapper for the
+  standard free() function in lowercase to keep the readability
+  consistent:
+
+#define my_free(_p) do {    \
+    free(_p);               \
+    (_p) = NULL;            \
+} while (0)
+
+- Use enums when defining more than one related constants. All enumeration
+  values are in UPPERCASE.
+- Avoid macros as much as possible and use inline functions, enums and const
+  variables wherever you can.
+- For macros encapsulating compound statements, right justify the backslashes
+  and enclose it in do { ... } while (0)
+- For parameterized macros, all the parameters used in the macro body must
+  be surrounded by parentheses. Eg:
+  #define ADD_1(_x) ((_x) + 1)
+
+- Use sizeof(varname) instead of sizeof(type) whenever possible. Eg:
+  char *p;
+  p = malloc(sizeof(*p));   /* good example */
+  p = malloc(sizeof(char)); /* bad example */
+
+- All variables should be declared at the beginning of a scope block {..}.
+  It is even preferred to declare all variables at the beginning of the
+  function so that all the local variable declarations is in one place and
+  we can see the comprehensive list in one glance.
+- Global structs should be declared at the top of the file in which they
+  are used, or in separate header files if they are used in multiple
+  source files.
+- Declarations of external functions and functions to appear later in the
+  source file should all go in one place near the beginning of the file,
+  somewhere before the first function definition in the file or else
+  should go in a header file.
+- Use of extern should be considered as evil, if it is used in header files
+  to reference global variables.
+- Don’t put extern declarations inside functions.
+
+- Usually every *.c file should have an associated *.h file. There are some
+  exceptions to this rule, such as unit tests and small *.c files containing
+  just the main() function.
+- Every header file in the source code must have preprocessor conditional
+  to prevent the header file from being scanned multiple times and avoiding
+  mutual dependency cycles. Alternatively you can use #pragma once directive,
+  as it avoids name clashes and increases the compile speed. Eg, for a
+  header file named foo.h, the entire contents of the header file must be
+  between the guard macros as follows:
+
+#ifndef _FOO_H_
+#define _FOO_H_
+...
+#endif /* _FOO_H_ */
+
+Or,
+
+#pragma once
+#ifndef _FOO_H_
+#define _FOO_H_
+...
+#endif /* _FOO_H_ */
+
+- Don't use #include when a forward declaration would suffice.
+- Functions defined in header files should be static inline.
+
+- Don’t make the program ugly just to placate GCC when extra warnings options
+  such as ‘-Wconversion’ or ‘-Wundef’ are used. These options can help in
+  finding bugs, but they can also generate so many false alarms that that
+  it hurts readability to silence them with unnecessary casts, wrappers, and
+  other complications.
+
+- Conditional compilation: when supporting configuration options already
+  known when building your program we prefer using if (... ) over conditional
+  compilation, as in the former case the compiler is able to perform more
+  extensive checking of all possible code paths. Eg, use:
+
+  if (HAS_FOO)
+    ...
+  else
+    ...
+
+instead of:
+
+  #ifdef HAS_FOO
+    ...
+  #else
+    ...
+  #endif
+
+  A modern compiler such as GCC will generate exactly the same code in both
+  cases and of course, the former method assumes that HAS_FOO is defined as
+  either 0 or 1.
+
+- Finally, rules are rules. Sometimes they are sensible and sometimes not
+  and regardless of your preference, we would like you to follow them.
+  A project is easier to follow if all project contributors follow the style
+  rules so that they can all read and understand everyone's code easily. But
+  remember, like all good rules, they are exceptions where it makes sense not
+  to be too rigid on the grounds of common sense and consistency!