+
+ </sect3>
+
+ </sect2>
+
+
+ <sect2 id="s15"><title>Using Space</title>
+
+
+
+ <sect3 id="s16"><title>Put braces on a line by themselves.</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>The brace needs to be on a line all by itself, not at the
+ end of the statement. Curly braces should line up with the
+ construct that they're associated with. This practice makes it
+ easier to identify the opening and closing braces for a
+ block.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+if ( this == that )
+{
+ ...
+}</programlisting>
+
+ <para><emphasis>Instead of:</emphasis></para>
+
+ <para>if ( this == that ) { ... }</para>
+
+ <para>or</para>
+
+ <para>if ( this == that ) { ... }</para>
+
+ <para><emphasis>Note:</emphasis> In the special case that the if-statement is
+ inside a loop, and it is trivial, i.e. it tests for a
+ condidtion that is obvious from the purpose of the block,
+ one-liners as above may optically preserve the loop structure
+ and make it easier to read.</para>
+
+ <para><emphasis>Status:</emphasis> developer-discrection.</para>
+
+ <para><emphasis>Example exception:</emphasis></para>
+<programlisting>
+while ( more lines are read )
+{
+ /* Please document what is/is not a comment line here */
+ if ( it's a comment ) continue;
+
+ do_something( line );
+}
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s17"><title>ALL control statements should have a
+ block</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>Using braces to make a block will make your code more
+ readable and less prone to error. All control statements should
+ have a block defined.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+if ( this == that )
+{
+ DoSomething();
+ DoSomethingElse();
+}</programlisting>
+
+ <para><emphasis>Instead of:</emphasis></para>
+
+ <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
+
+ <para>or</para>
+
+ <para>if ( this == that ) DoSomething();</para>
+
+ <para><emphasis>Note:</emphasis> The first example in "Instead of" will execute
+ in a manner other than that which the developer desired (per
+ indentation). Using code braces would have prevented this
+ "feature". The "explanation" and "exception" from the point
+ above also applies.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s18"><title>Do not belabor/blow-up boolean
+ expressions</title>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+structure->flag = ( condition );</programlisting>
+
+ <para><emphasis>Instead of:</emphasis></para>
+
+ <para>if ( condition ) { structure->flag = 1; } else {
+ structure->flag = 0; }</para>
+
+ <para><emphasis>Note:</emphasis> The former is readable and consice. The later
+ is wordy and inefficient. Please assume that any developer new
+ to the project has at least a "good" knowledge of C/C++. (Hope
+ I do not offend by that last comment ... 8-)</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s19"><title>Use white space freely because it is
+ free</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>Make it readable. The notable exception to using white space
+ freely is listed in the next guideline.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+int firstValue = 0;
+int someValue = 0;
+int anotherValue = 0;
+int thisVariable = 0;
+
+if ( thisVariable == thatVariable )
+
+firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s20"><title>Don't use white space around structure
+ operators</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>- structure pointer operator ( "->" ) - member operator (
+ "." ) - functions and parentheses</para>
+
+ <para>It is a general coding practice to put pointers, references,
+ and function parentheses next to names. With spaces, the
+ connection between the object and variable/function name is not
+ as clear.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+aStruct->aMember;
+aStruct.aMember;
+FunctionName();</programlisting>
+
+ <para><emphasis>Instead of:</emphasis> aStruct -> aMember; aStruct . aMember;
+ FunctionName ();</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s21"><title>Make the last brace of a function stand
+ out</title>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+int function1( ... )
+{
+ ...code...
+ return( retCode );
+
+} /* -END- function1 */
+
+
+int function2( ... )
+{
+} /* -END- function2 */
+</programlisting>
+
+ <para><emphasis>Instead of:</emphasis></para>
+
+ <para>int function1( ... ) { ...code... return( retCode ); } int
+ function2( ... ) { }</para>
+
+ <para><emphasis>Note:</emphasis> Use 1 blank line before the closing brace and 2
+ lines afterwards. This makes the end of function standout to
+ the most casual viewer. Although function comments help
+ seperate functions, this is still a good coding practice. In
+ fact, I follow these rules when using blocks in "for", "while",
+ "do" loops, and long if {} statements too. After all whitespace
+ is free!</para>
+
+ <para><emphasis>Status:</emphasis> developer-discrection on the number of blank
+ lines. Enforced is the end of function comments.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s22"><title>Use 3 character indentions</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>If some use 8 character TABs and some use 3 character TABs,
+ the code can look *very* ragged. So use 3 character indentions
+ only. If you like to use TABs, pass your code through a filter
+ such as "expand -t3" before checking in your code.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+static const char * const url_code_map[256] =
+{
+ NULL, ...
+};
+
+
+int function1( ... )
+{
+ if ( 1 )
+ {
+ return( ALWAYS_TRUE );
+ }
+ else
+ {
+ return( HOW_DID_YOU_GET_HERE );
+ }
+
+ return( NEVER_GETS_HERE );
+
+}
+</programlisting>
+ </sect3>
+
+ </sect2>
+
+
+ <sect2 id="s23"><title>Initializing</title>
+
+
+
+ <sect3 id="s24"><title>Initialize all variables</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>Do not assume that the variables declared will not be used
+ until after they have been assigned a value somewhere else in
+ the code. Remove the chance of accidentally using an unassigned
+ variable.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+short anShort = 0;
+float aFloat = 0;
+struct *ptr = NULL;</programlisting>
+
+ <para><emphasis>Note:</emphasis> It is much easier to debug a SIGSEGV if the
+ message says you are trying to access memory address 00000000
+ and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
+ arrayPtr[0].</para>
+
+ <para><emphasis>Status:</emphasis> developer-discrection if and only if the
+ variable is assigned a value "shortly after" declaration.</para>
+
+ </sect3>
+ </sect2>
+
+
+ <sect2 id="s25"><title>Functions</title>
+
+
+
+ <sect3 id="s26"><title>Name functions that return a boolean as a
+ question.</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>Value should be phrased as a question that would logically
+ be answered as a true or false statement</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+ShouldWeBlockThis();
+ContainsAnImage();
+IsWebPageBlank();
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s27"><title>Always specify a return type for a
+ function.</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>The default return for a function is an int. To avoid
+ ambiguity, create a return for a function when the return has a
+ purpose, and create a void return type if the function does not
+ need to return anything.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s28"><title>Minimize function calls when iterating by
+ using variables</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>It is easy to write the following code, and a clear argument
+ can be made that the code is easy to understand:</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+{
+ ....
+}</programlisting>
+
+ <para><emphasis>Note:</emphasis> Unfortunately, this makes a function call for
+ each and every iteration. This increases the overhead in the
+ program, because the compiler has to look up the function each
+ time, call it, and return a value. Depending on what occurs in
+ the blockListLength() call, it might even be creating and
+ destroying structures with each iteration, even though in each
+ case it is comparing "cnt" to the same value, over and over.
+ Remember too - even a call to blockListLength() is a function
+ call, with the same overhead.</para>
+
+ <para>Instead of using a function call during the iterations,
+ assign the value to a variable, and evaluate using the
+ variable.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+size_t len = blockListLength();
+
+for ( size_t cnt = 0; cnt < len; cnt ++ )
+{
+ ....
+}</programlisting>
+
+ <para><emphasis>Exceptions:</emphasis> if the value of blockListLength() *may*
+ change or could *potentially* change, then you must code the
+ function call in the for/while loop.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s29"><title>Pass and Return by Const Reference</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>This allows a developer to define a const pointer and call
+ your function. If your function does not have the const
+ keyword, we may not be able to use your function. Consider
+ strcmp, if it were defined as: extern int strcmp( char *s1,
+ char *s2 );</para>
+
+ <para>I could then not use it to compare argv's in main: int main(
+ int argc, const char *argv[] ) { strcmp( argv[0], "foobars"
+ ); }</para>
+
+ <para>Both these pointers are *const*! If the c runtime library
+ maintainers do it, we should too.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s30"><title>Pass and Return by Value</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>Most structures cannot fit onto a normal stack entry (i.e.
+ they are not 4 bytes or less). Aka, a function declaration
+ like: int load_aclfile( struct client_state csp )</para>
+
+ <para>would not work. So, to be consistent, we should declare all
+ prototypes with "pass by value": int load_aclfile( struct
+ client_state *csp )</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s31"><title>Names of include files</title>
+
+ <para><emphasis>Explanation:</emphasis></para>
+
+ <para>Your include statements should contain the file name without
+ a path. The path should be listed in the Makefile, using -I as
+ processor directive to search the indicated paths. An exception
+ to this would be for some proprietary software that utilizes a
+ partial path to distinguish their header files from system or
+ other header files.</para>
+
+ <para><emphasis>Example:</emphasis></para>
+<programlisting>
+#include <iostream.h> /* This is not a local include */
+#include "config.h" /* This IS a local include */
+</programlisting>
+
+ <para><emphasis>Exception:</emphasis></para>
+
+ <para>
+<programlisting>
+/* This is not a local include, but requires a path element. */
+#include <sys/fileName.h>
+</programlisting>