+
+ </sect3>
+
+
+ <sect3 id="s13"><title>Enumerations, and #defines</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>Use all capital letters, with underscores between words. Do
+ not start an identifier with an underscore. (ANSI C reserves
+ these for use by the compiler and system headers.)</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+(enumeration) : enum Boolean { FALSE, TRUE };
+(#define) : #define DEFAULT_SIZE 100;</programlisting>
+
+ <para><emphasis>Note:</> We have a standard naming scheme for #defines
+ that toggle a feature in the preprocessor: FEATURE_>, where
+ > is a short (preferably 1 or 2 word) description.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+#define FEATURE_FORCE 1
+
+#ifdef FEATURE_FORCE
+#define FORCE_PREFIX blah
+#endif /* def FEATURE_FORCE */
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s14"><title>Constants</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>Spell common words out entirely (do not remove vowels).</para>
+
+ <para>Use only widely-known domain acronyms and abbreviations.
+ Capitalize all letters of an acronym.</para>
+
+ <para>Use underscore (_) to separate adjacent acronyms and
+ abbreviations. Never terminate a name with an underscore.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+#define USE_IMAGE_LIST 1</programlisting>
+
+ <para><emphasis>Instead of:</></para>
+
+ <para>
+<programlisting>
+#define USE_IMG_LST 1 or
+#define _USE_IMAGE_LIST 1 or
+#define USE_IMAGE_LIST_ 1 or
+#define use_image_list 1 or
+#define UseImageList 1
+</programlisting>
+</para>
+
+
+ </sect3>
+
+ </sect2>
+
+
+ <sect2 id="s15"><title>Using Space</title>
+
+
+
+ <sect3 id="s16"><title>Put braces on a line by themselves.</title>
+
+ <para><emphasis>Explanation:</></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:</></para>
+<programlisting>
+if ( this == that )
+{
+ ...
+}</programlisting>
+
+ <para><emphasis>Instead of:</></para>
+
+ <para>if ( this == that ) { ... }</para>
+
+ <para>or</para>
+
+ <para>if ( this == that ) { ... }</para>
+
+ <para><emphasis>Note:</> 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:</> developer-discrection.</para>
+
+ <para><emphasis>Example exception:</></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:</></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:</></para>
+<programlisting>
+if ( this == that )
+{
+ DoSomething();
+ DoSomethingElse();
+}</programlisting>
+
+ <para><emphasis>Instead of:</></para>
+
+ <para>if ( this == that ) DoSomething(); DoSomethingElse();</para>
+
+ <para>or</para>
+
+ <para>if ( this == that ) DoSomething();</para>
+
+ <para><emphasis>Note:</> 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:</></para>
+<programlisting>
+structure->flag = ( condition );</programlisting>
+
+ <para><emphasis>Instead of:</></para>
+
+ <para>if ( condition ) { structure->flag = 1; } else {
+ structure->flag = 0; }</para>
+
+ <para><emphasis>Note:</> 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:</></para>
+
+ <para>Make it readable. The notable exception to using white space
+ freely is listed in the next guideline.</para>
+
+ <para><emphasis>Example:</></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:</></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:</></para>
+<programlisting>
+aStruct->aMember;
+aStruct.aMember;
+FunctionName();</programlisting>
+
+ <para><emphasis>Instead of:</> aStruct -> aMember; aStruct . aMember;
+ FunctionName ();</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s21"><title>Make the last brace of a function stand
+ out</title>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+int function1( ... )
+{
+ ...code...
+ return( retCode );
+
+} /* -END- function1 */
+
+
+int function2( ... )
+{
+} /* -END- function2 */
+</programlisting>
+
+ <para><emphasis>Instead of:</></para>
+
+ <para>int function1( ... ) { ...code... return( retCode ); } int
+ function2( ... ) { }</para>
+
+ <para><emphasis>Note:</> 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:</> 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:</></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:</></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:</></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:</></para>
+<programlisting>
+short anShort = 0;
+float aFloat = 0;
+struct *ptr = NULL;</programlisting>
+
+ <para><emphasis>Note:</> 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:</> 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:</></para>
+
+ <para>Value should be phrased as a question that would logically
+ be answered as a true or false statement</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+ShouldWeBlockThis();
+ContainsAnImage();
+IsWebPageBlank();
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s27"><title>Always specify a return type for a
+ function.</title>
+
+ <para><emphasis>Explanation:</></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:</></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:</></para>
+<programlisting>
+for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+{
+ ....
+}</programlisting>
+
+ <para><emphasis>Note:</> 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:</></para>
+<programlisting>
+size_t len = blockListLength();
+
+for ( size_t cnt = 0; cnt < len; cnt ++ )
+{
+ ....
+}</programlisting>
+
+ <para><emphasis>Exceptions:</> 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:</></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], "junkbusters"
+ ); }</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:</></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:</></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:</></para>
+<programlisting>
+#include <iostream.h> /* This is not a local include */
+#include "config.h" /* This IS a local include */
+</programlisting>
+
+ <para><emphasis>Exception:</></para>
+
+ <para>
+<programlisting>
+/* This is not a local include, but requires a path element. */
+#include <sys/fileName.h>
+</programlisting>
+</para>
+
+ <para><emphasis>Note:</> Please! do not add "-I." to the Makefile
+ without a _very_ good reason. This duplicates the #include
+ "file.h" behaviour.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s32"><title>Provide multiple inclusion
+ protection</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>Prevents compiler and linker errors resulting from
+ redefinition of items.</para>
+
+ <para>Wrap each header file with the following syntax to prevent
+ multiple inclusions of the file. Of course, replace PROJECT_H
+ with your file name, with "." Changed to "_", and make it
+ uppercase.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+#ifndef PROJECT_H_INCLUDED
+#define PROJECT_H_INCLUDED
+ ...
+#endif /* ndef PROJECT_H_INCLUDED */
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s33"><title>Use `extern "C"` when appropriate</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>If our headers are included from C++, they must declare our
+ functions as `extern "C"`. This has no cost in C, but increases
+ the potential re-usability of our code.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+#ifdef __cplusplus
+extern "C"
+{
+#endif /* def __cplusplus */
+
+... function definitions here ...
+
+#ifdef __cplusplus
+}
+#endif /* def __cplusplus */
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s34"><title>Where Possible, Use Forward Struct
+ Declaration Instead of Includes</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>Useful in headers that include pointers to other struct's.
+ Modifications to excess header files may cause needless
+ compiles.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+/*********************************************************************
+ * We're avoiding an include statement here!
+ *********************************************************************/
+struct file_list;
+extern file_list *xyz;</programlisting>
+
+ <para><emphasis>Note:</> If you declare "file_list xyz;" (without the
+ pointer), then including the proper header file is necessary.
+ If you only want to prototype a pointer, however, the header
+ file is unneccessary.</para>
+
+ <para><emphasis>Status:</> Use with discrection.</para>
+
+
+ </sect3>
+ </sect2>
+
+ <sect2 id="s35"><title>General Coding Practices</title>
+
+
+
+ <sect3 id="s36"><title>Turn on warnings</title>
+
+ <para><emphasis>Explanation</></para>
+
+ <para>Compiler warnings are meant to help you find bugs. You
+ should turn on as many as possible. With GCC, the switch is
+ "-Wall". Try and fix as many warnings as possible.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s37"><title>Provide a default case for all switch
+ statements</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>What you think is guaranteed is never really guaranteed. The
+ value that you don't think you need to check is the one that
+ someday will be passed. So, to protect yourself from the
+ unknown, always have a default step in a switch statement.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+switch( hash_string( cmd ) )
+{
+ case hash_actions_file :
+ ... code ...
+ break;
+
+ case hash_confdir :
+ ... code ...
+ break;
+
+ default :
+ log_error( ... );
+ ... anomly code goes here ...
+ continue; / break; / exit( 1 ); / etc ...
+
+} /* end switch( hash_string( cmd ) ) */</programlisting>
+
+ <para><emphasis>Note:</> If you already have a default condition, you
+ are obviously exempt from this point. Of note, most of the
+ WIN32 code calls `DefWindowProc' after the switch statement.
+ This API call *should* be included in a default statement.</para>
+
+ <para><emphasis>Another Note:</> This is not so much a readability issue
+ as a robust programming issue. The "anomly code goes here" may
+ be no more than a print to the STDERR stream (as in
+ load_config). Or it may really be an ABEND condition.</para>
+
+ <para><emphasis>Status:</> Programmer discretion is advised.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s38"><title>Try to avoid falling through cases in a
+ switch statement.</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>In general, you will want to have a 'break' statement within
+ each 'case' of a switch statement. This allows for the code to
+ be more readable and understandable, and furthermore can
+ prevent unwanted surprises if someone else later gets creative
+ and moves the code around.</para>
+
+ <para>The language allows you to plan the fall through from one
+ case statement to another simply by omitting the break
+ statement within the case statement. This feature does have
+ benefits, but should only be used in rare cases. In general,
+ use a break statement for each case statement.</para>
+
+ <para>If you choose to allow fall through, you should comment both
+ the fact of the fall through and reason why you felt it was
+ necessary.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s39"><title>Use 'long' or 'short' Instead of
+ 'int'</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>On 32-bit platforms, int usually has the range of long. On
+ 16-bit platforms, int has the range of short.</para>
+
+ <para><emphasis>Status:</> open-to-debate. In the case of most FSF
+ projects (including X/GNU-Emacs), there are typedefs to int4,
+ int8, int16, (or equivalence ... I forget the exact typedefs
+ now). Should we add these to IJB now that we have a "configure"
+ script?</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s40"><title>Don't mix size_t and other types</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>The type of size_t varies across platforms. Do not make
+ assumptions about whether it is signed or unsigned, or about
+ how long it is. Do not compare a size_t against another
+ variable of a different type (or even against a constant)
+ without casting one of the values. Try to avoid using size_t if
+ you can.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s41"><title>Declare each variable and struct on its
+ own line.</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>It can be tempting to declare a series of variables all on
+ one line. Don't.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+long a = 0;
+long b = 0;
+long c = 0;</programlisting>
+
+ <para><emphasis>Instead of:</></para>
+
+ <para>long a, b, c;</para>
+
+ <para><emphasis>Explanation:</> - there is more room for comments on the
+ individual variables - easier to add new variables without
+ messing up the original ones - when searching on a variable to
+ find its type, there is less clutter to "visually"
+ eliminate</para>
+
+ <para><emphasis>Exceptions:</> when you want to declare a bunch of loop
+ variables or other trivial variables; feel free to declare them
+ on 1 line. You should, although, provide a good comment on
+ their functions.</para>
+
+ <para><emphasis>Status:</> developer-discrection.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s42"><title>Use malloc/zalloc sparingly</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>Create a local stuct (on the stack) if the variable will
+ live and die within the context of one function call.</para>
+
+ <para>Only "malloc" a struct (on the heap) if the variable's life
+ will extend beyond the context of one function call.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+If a function creates a struct and stores a pointer to it in a
+list, then it should definately be allocated via `malloc'.
+</programlisting>
+ </sect3>
+
+
+ <sect3 id="s43"><title>The Programmer Who Uses 'malloc' is
+ Responsible for Ensuring 'free'</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>If you have to "malloc" an instance, you are responsible for
+ insuring that the instance is `free'd, even if the deallocation
+ event falls within some other programmer's code. You are also
+ responsible for ensuring that deletion is timely (i.e. not too
+ soon, not too late). This is known as "low-coupling" and is a
+ "good thing (tm)". You may need to offer a
+ free/unload/destuctor type function to accomodate this.</para>
+
+ <para><emphasis>Example:</></para>
+<programlisting>
+int load_re_filterfile( struct client_state *csp ) { ... }
+static void unload_re_filterfile( void *f ) { ... }</programlisting>
+
+ <para><emphasis>Exceptions:</></para>
+
+ <para>The developer cannot be expected to provide `free'ing
+ functions for C run-time library functions ... such as
+ `strdup'.</para>
+
+ <para><emphasis>Status:</> developer-discrection. The "main" use of this
+ standard is for allocating and freeing data structures (complex
+ or nested).</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s44"><title>Add loaders to the `file_list' structure
+ and in order</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>I have ordered all of the "blocker" file code to be in alpha
+ order. It is easier to add/read new blockers when you expect a
+ certain order.</para>
+
+ <para><emphasis>Note:</> It may appear that the alpha order is broken in
+ places by POPUP tests coming before PCRS tests. But since
+ POPUPs can also be referred to as KILLPOPUPs, it is clear that
+ it should come first.</para>
+
+
+ </sect3>
+
+
+ <sect3 id="s45"><title>"Uncertain" new code and/or changes to
+ exitinst code, use FIXME</title>
+
+ <para><emphasis>Explanation:</></para>
+
+ <para>If you have enough confidence in new code or confidence in
+ your changes, but are not *quite* sure of the reprocussions,
+ add this:</para>
+
+ <para>/* FIXME: this code has a logic error on platform XYZ, *
+ attempthing to fix */ #ifdef PLATFORM ...changed code here...
+ #endif</para>
+
+ <para>or:</para>
+
+ <para>/* FIXME: I think the original author really meant this...
+ */ ...changed code here...</para>
+
+ <para>or:</para>
+
+ <para>/* FIXME: new code that *may* break something else... */
+ ...new code here...</para>
+
+ <para><emphasis>Note:</> If you make it clear that this may or may not
+ be a "good thing (tm)", it will be easier to identify and
+ include in the project (or conversly exclude from the
+ project).</para>
+
+
+ </sect3>
+
+ </sect2>
+
+ <sect2 id="s46"><title>Addendum: Template for files and function
+ comment blocks:</title>
+
+ <para><emphasis>Example for file comments:</></para>
+<programlisting>
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.2 2001/09/13 15:20:17 swa Exp $";
+/*********************************************************************
+ *
+ * File : $S<!-- Break CVS Substitution -->ource$
+ *
+ * Purpose : (Fill me in with a good description!)
+ *
+ * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * IJBSWA team. http://ijbswa.sourceforge.net
+ *
+ * Based on the Internet Junkbuster originally written
+ * by and Copyright (C) 1997 Anonymous Coders and
+ * Junkbusters Corporation. http://www.junkbusters.com
+ *
+ * This program is free software; you can redistribute it
+ * and/or modify it under the terms of the GNU General
+ * Public License as published by the Free Software
+ * Foundation; either version 2 of the License, or (at
+ * your option) any later version.
+ *
+ * This program is distributed in the hope that it will
+ * be useful, but WITHOUT ANY WARRANTY; without even the
+ * implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU General Public
+ * License for more details.
+ *
+ * The GNU General Public License should be included with
+ * this file. If not, you can view it at
+ * http://www.gnu.org/copyleft/gpl.html
+ * or write to the Free Software Foundation, Inc., 59
+ * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ * Revisions :
+ * $L<!-- Break CVS Substitution -->og$
+ *
+ *********************************************************************/
+
+
+#include "config.h"
+
+ ...necessary include files for us to do our work...
+
+const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
+</programlisting>
+
+ <para><emphasis>Note:</> This declares the rcs variables that should be
+ added to the "show-proxy-args" page. If this is a brand new
+ creation by you, you are free to change the "Copyright" section
+ to represent the rights you wish to maintain.</para>
+
+ <para><emphasis>Note:</> The formfeed character that is present right
+ after the comment flower box is handy for (X|GNU)Emacs users to
+ skip the verbige and get to the heart of the code (via
+ `forward-page' and `backward-page'). Please include it if you
+ can.</para>
+
+ <para><emphasis>Example for file header comments:</></para>
+<programlisting>
+#ifndef _FILENAME_H
+#define _FILENAME_H
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.2 2001/09/13 15:20:17 swa Exp $"
+/*********************************************************************
+ *
+ * File : $S<!-- Break CVS Substitution -->ource$
+ *
+ * Purpose : (Fill me in with a good description!)
+ *
+ * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * IJBSWA team. http://ijbswa.sourceforge.net
+ *
+ * Based on the Internet Junkbuster originally written
+ * by and Copyright (C) 1997 Anonymous Coders and
+ * Junkbusters Corporation. http://www.junkbusters.com
+ *
+ * This program is free software; you can redistribute it
+ * and/or modify it under the terms of the GNU General
+ * Public License as published by the Free Software
+ * Foundation; either version 2 of the License, or (at
+ * your option) any later version.
+ *
+ * This program is distributed in the hope that it will
+ * be useful, but WITHOUT ANY WARRANTY; without even the
+ * implied warranty of MERCHANTABILITY or FITNESS FOR A
+ * PARTICULAR PURPOSE. See the GNU General Public
+ * License for more details.
+ *
+ * The GNU General Public License should be included with
+ * this file. If not, you can view it at
+ * http://www.gnu.org/copyleft/gpl.html
+ * or write to the Free Software Foundation, Inc., 59
+ * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ *
+ * Revisions :
+ * $L<!-- Break CVS Substitution -->og$
+ *
+ *********************************************************************/
+
+
+#include "project.h"
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+ ... function headers here ...
+
+
+/* Revision control strings from this header and associated .c file */
+extern const char FILENAME_rcs[];
+extern const char FILENAME_h_rcs[];
+
+
+#ifdef __cplusplus
+} /* extern "C" */
+#endif
+
+#endif /* ndef _FILENAME_H */
+
+/*
+ Local Variables:
+ tab-width: 3
+ end:
+*/
+</programlisting>
+
+ <para><emphasis>Example for function comments:</></para>
+<programlisting>
+/*********************************************************************
+ *
+ * Function : FUNCTION_NAME
+ *
+ * Description : (Fill me in with a good description!)
+ *
+ * Parameters :
+ * 1 : param1 = pointer to an important thing
+ * 2 : x = pointer to something else
+ *
+ * Returns : 0 => Ok, everything else is an error.
+ *
+ *********************************************************************/
+int FUNCTION_NAME( void *param1, const char *x )
+{
+ ...
+ return( 0 );
+
+}
+</programlisting>
+
+ <para><emphasis>Note:</> If we all follow this practice, we should be
+ able to parse our code to create a "self-documenting" web
+ page.</para>
+
+ </sect2>
+
+ </sect1>
+
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect1 id="cvs"><title>Version Control Guidelines</title>
+ <para>To be filled. note on cvs comments. don't comment what you did, comment
+why you did it.
+</para>
+ </sect1>
+
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect1 id="testing"><title>Testing Guidelines</title>
+ <para>To be filled.
+</para>
+
+ <!-- ~~~~~ New section ~~~~~ -->
+ <sect2 id="testing-plan"><title>Testplan for releases</title>
+ <para>
+Explain release numbers. major, minor. developer releases. etc.
+