new stylesheet for docs. new stylesheet for web.

[privoxy.git] / doc / text / developer-manual.txt

Privoxy Developer Manual

   By: Privoxy Developers
   
   $Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:41 hal9 Exp $
   
   The developer manual gives the users information on how to help the
   developer team. It provides guidance on coding, testing, documentation
   and other issues.
   
   Privoxy is a web proxy with advanced filtering capabilities for
   protecting privacy, filtering web page content, managing cookies,
   controlling access, and removing ads, banners, pop-ups and other
   obnoxious Internet junk. Privoxy has a very flexible configuration and
   can be customized to suit individual needs and tastes. Privoxy has
   application for both stand-alone systems and multi-user networks.
   
   Privoxy is based on the code of the Internet Junkbuster. Junkbuster
   was originally written by JunkBusters Corporation, and was released as
   free open-source software under the GNU GPL. Stefan Waldherr made many
   improvements, and started the SourceForge project to continue
   development. Other developers have since joined Stefan.
   
   You can find the latest version of the user manual at
   [1]http://www.privoxy.org/developer-manual/. Please see the Contact
   section in the user-manual if you want to contact the developers.
     _________________________________________________________________
   
   Table of Contents
   1. [2]Introduction
   2. [3]Quickstart to Privoxy Development
   3. [4]Documentation Guidelines
   4. [5]Coding Guidelines
          
        4.1. [6]Introduction
        4.2. [7]Using Comments
                
              4.2.1. [8]Comment, Comment, Comment
              4.2.2. [9]Use blocks for comments
              4.2.3. [10]Keep Comments on their own line
              4.2.4. [11]Comment each logical step
              4.2.5. [12]Comment All Functions Thoroughly
              4.2.6. [13]Comment at the end of braces if the content is
                      more than one screen length
                      
        4.3. [14]Naming Conventions
                
              4.3.1. [15]Variable Names
              4.3.2. [16]Function Names
              4.3.3. [17]Header file prototypes
              4.3.4. [18]Enumerations, and #defines
              4.3.5. [19]Constants
                      
        4.4. [20]Using Space
                
              4.4.1. [21]Put braces on a line by themselves.
              4.4.2. [22]ALL control statements should have a block
              4.4.3. [23]Do not belabor/blow-up boolean expressions
              4.4.4. [24]Use white space freely because it is free
              4.4.5. [25]Don't use white space around structure operators
              4.4.6. [26]Make the last brace of a function stand out
              4.4.7. [27]Use 3 character indentions
                      
        4.5. [28]Initializing
                
              4.5.1. [29]Initialize all variables
                      
        4.6. [30]Functions
                
              4.6.1. [31]Name functions that return a boolean as a
                      question.
                      
              4.6.2. [32]Always specify a return type for a function.
              4.6.3. [33]Minimize function calls when iterating by using
                      variables
                      
              4.6.4. [34]Pass and Return by Const Reference
              4.6.5. [35]Pass and Return by Value
              4.6.6. [36]Names of include files
              4.6.7. [37]Provide multiple inclusion protection
              4.6.8. [38]Use `extern "C"` when appropriate
              4.6.9. [39]Where Possible, Use Forward Struct Declaration
                      Instead of Includes
                      
        4.7. [40]General Coding Practices
                
              4.7.1. [41]Turn on warnings
              4.7.2. [42]Provide a default case for all switch statements
              4.7.3. [43]Try to avoid falling through cases in a switch
                      statement.
                      
              4.7.4. [44]Use 'long' or 'short' Instead of 'int'
              4.7.5. [45]Don't mix size_t and other types
              4.7.6. [46]Declare each variable and struct on its own
                      line.
                      
              4.7.7. [47]Use malloc/zalloc sparingly
              4.7.8. [48]The Programmer Who Uses 'malloc' is Responsible
                      for Ensuring 'free'
                      
              4.7.9. [49]Add loaders to the `file_list' structure and in
                      order
                      
              4.7.10. [50]"Uncertain" new code and/or changes to exitinst
                      code, use FIXME
                      
        4.8. [51]Addendum: Template for files and function comment
                blocks:
                
   5. [52]Version Control Guidelines
   6. [53]Testing Guidelines
          
        6.1. [54]Testplan for releases
        6.2. [55]Test reports
                
   7. [56]Contact the developers
   8. [57]Copyright and History
   9. [58]See also
          
1. Introduction

   To be filled.
     _________________________________________________________________
   
2. Quickstart to Privoxy Development

   You'll need an account on Sourceforge to support our development. Mail
   you ID to the list and wait until a project manager has added you. For
   the time beeing (read, this section is under construction), please
   note the following guidelines for changing stuff in the code. If it is
   
    1. A bugfix / clean-up / cosmetic thing: shoot
    2. A new feature that can be turned off: shoot
    3. A clear improvement w/o side effects on other parts of the code:
       shoot
    4. A matter of taste: ask the list
    5. A major redesign of some part of the code: ask the list
     _________________________________________________________________
   
3. Documentation Guidelines

   All docs are in SGML format and located in the doc/source directory.
   
   How do you update the webserver (i.e. the pages on sourceforge)?
   
    1. Run make dok (which uses the documents in doc/source to update all
       text files in doc/text and to update all web documents in
       doc/webserver.
    2. Run make webserver which copies all files from doc/webserver to
       the sourceforge webserver via scp.
     _________________________________________________________________
   
4. Coding Guidelines

4.1. Introduction

   This set of standards is designed to make our lives easier. It is
   developed with the simple goal of helping us keep the "new and
   improved Privoxy" consistent and reliable. Thus making maintenance
   easier and increasing chances of success of the project.
   
   And that of course comes back to us as individuals. If we can increase
   our development and product efficiencies then we can solve more of the
   request for changes/improvements and in general feel good about
   ourselves. ;->
     _________________________________________________________________
   
4.2. Using Comments

4.2.1. Comment, Comment, Comment

   Explanation:
   
   Comment as much as possible without commenting the obvious. For
   example do not comment "aVariable is equal to bVariable". Instead
   explain why aVariable should be equal to the bVariable. Just because a
   person can read code does not mean they will understand why or what is
   being done. A reader may spend a lot more time figuring out what is
   going on when a simple comment or explanation would have prevented the
   extra research. Please help your brother IJB'ers out!
   
   The comments will also help justify the intent of the code. If the
   comment describes something different than what the code is doing then
   maybe a programming error is occurring.
   
   Example:
/* if page size greater than 1k ... */
if ( PageLength() > 1024 )
{
    ... "block" the page up ...
}

/* if page size is small, send it in blocks */
if ( PageLength() > 1024 )
{
    ... "block" the page up ...
}

This demonstrates 2 cases of "what not to do".  The first is a
"syntax comment".  The second is a comment that does not fit what
is actually being done.
     _________________________________________________________________
   
4.2.2. Use blocks for comments

   Explanation:
   
   Comments can help or they can clutter. They help when they are
   differentiated from the code they describe. One line comments do not
   offer effective separation between the comment and the code. Block
   identifiers do, by surrounding the code with a clear, definable
   pattern.
   
   Example:
/*********************************************************************
 * This will stand out clearly in your code!
 *********************************************************************/
if ( thisVariable == thatVariable )
{
   DoSomethingVeryImportant();
}


/* unfortunately, this may not */
if ( thisVariable == thatVariable )
{
   DoSomethingVeryImportant();
}


if ( thisVariable == thatVariable ) /* this may not either */
{
   DoSomethingVeryImportant();
}

   Exception:
   
   If you are trying to add a small logic comment and do not wish to
   "disrubt" the flow of the code, feel free to use a 1 line comment
   which is NOT on the same line as the code.
     _________________________________________________________________
   
4.2.3. Keep Comments on their own line

   Explanation:
   
   It goes back to the question of readability. If the comment is on the
   same line as the code it will be harder to read than the comment that
   is on its own line.
   
   There are three exceptions to this rule, which should be violated
   freely and often: during the definition of variables, at the end of
   closing braces, when used to comment parameters.
   
   Example:
/*********************************************************************
 * This will stand out clearly in your code,
 * But the second example won't.
 *********************************************************************/
if ( thisVariable == thatVariable )
{
   DoSomethingVeryImportant();
}

if ( thisVariable == thatVariable ) /*can you see me?*/
{
   DoSomethingVeryImportant(); /*not easily*/
}


/*********************************************************************
 * But, the encouraged exceptions:
 *********************************************************************/
int urls_read     = 0;     /* # of urls read + rejected */
int urls_rejected = 0;     /* # of urls rejected */

if ( 1 == X )
{
   DoSomethingVeryImportant();
}


short DoSomethingVeryImportant(
   short firstparam,   /* represents something */
   short nextparam     /* represents something else */ )
{
   ...code here...

}   /* -END- DoSomethingVeryImportant */
     _________________________________________________________________
   
4.2.4. Comment each logical step

   Explanation:
   
   Logical steps should be commented to help others follow the intent of
   the written code and comments will make the code more readable.
   
   If you have 25 lines of code without a comment, you should probably go
   back into it to see where you forgot to put one.
   
   Most "for", "while", "do", etc... loops _probably_ need a comment.
   After all, these are usually major logic containers.
     _________________________________________________________________
   
4.2.5. Comment All Functions Thoroughly

   Explanation:
   
   A reader of the code should be able to look at the comments just prior
   to the beginning of a function and discern the reason for its
   existence and the consequences of using it. The reader should not have
   to read through the code to determine if a given function is safe for
   a desired use. The proper information thoroughly presented at the
   introduction of a function not only saves time for subsequent
   maintenance or debugging, it more importantly aids in code reuse by
   allowing a user to determine the safety and applicability of any
   function for the problem at hand. As a result of such benefits, all
   functions should contain the information presented in the addendum
   section of this document.
     _________________________________________________________________
   
4.2.6. Comment at the end of braces if the content is more than one screen
length

   Explanation:
   
   Each closing brace should be followed on the same line by a comment
   that describes the origination of the brace if the original brace is
   off of the screen, or otherwise far away from the closing brace. This
   will simplify the debugging, maintenance, and readability of the code.
   
   As a suggestion , use the following flags to make the comment and its
   brace more readable:
   
   use following a closing brace: } /* -END- if() or while () or etc...
   */
   
   Example:
if ( 1 == X )
{
   DoSomethingVeryImportant();
   ...some long list of commands...
} /* -END- if x is 1 */

or:

if ( 1 == X )
{
   DoSomethingVeryImportant();
   ...some long list of commands...
} /* -END- if ( 1 == X ) */
     _________________________________________________________________
   
4.3. Naming Conventions

4.3.1. Variable Names

   Explanation:
   
   Use all lowercase, and seperate words via an underscore ('_'). Do not
   start an identifier with an underscore. (ANSI C reserves these for use
   by the compiler and system headers.) Do not use identifiers which are
   reserved in ANSI C++. (E.g. template, class, true, false, ...). This
   is in case we ever decide to port Privoxy to C++.
   
   Example:
int ms_iis5_hack = 0;

   Instead of:
   
int msiis5hack = 0; int msIis5Hack = 0;
     _________________________________________________________________
   
4.3.2. Function Names

   Explanation:
   
   Use all lowercase, and seperate words via an underscore ('_'). Do not
   start an identifier with an underscore. (ANSI C reserves these for use
   by the compiler and system headers.) Do not use identifiers which are
   reserved in ANSI C++. (E.g. template, class, true, false, ...). This
   is in case we ever decide to port Privoxy to C++.
   
   Example:
int load_some_file( struct client_state *csp )

   Instead of:
   
int loadsomefile( struct client_state *csp )
int loadSomeFile( struct client_state *csp )
     _________________________________________________________________
   
4.3.3. Header file prototypes

   Explanation:
   
   Use a descriptive parameter name in the function prototype in header
   files. Use the same parameter name in the header file that you use in
   the c file.
   
   Example:
(.h) extern int load_aclfile( struct client_state *csp );
(.c) int load_aclfile( struct client_state *csp )

   Instead of:
(.h) extern int load_aclfile( struct client_state * ); or
(.h) extern int load_aclfile();
(.c) int load_aclfile( struct client_state *csp )
     _________________________________________________________________
   
4.3.4. Enumerations, and #defines

   Explanation:
   
   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.)
   
   Example:
(enumeration) : enum Boolean { FALSE, TRUE };
(#define) : #define DEFAULT_SIZE 100;

   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.
   
   Example:
#define FEATURE_FORCE 1

#ifdef FEATURE_FORCE
#define FORCE_PREFIX blah
#endif /* def FEATURE_FORCE */
     _________________________________________________________________
   
4.3.5. Constants

   Explanation:
   
   Spell common words out entirely (do not remove vowels).
   
   Use only widely-known domain acronyms and abbreviations. Capitalize
   all letters of an acronym.
   
   Use underscore (_) to separate adjacent acronyms and abbreviations.
   Never terminate a name with an underscore.
   
   Example:
#define USE_IMAGE_LIST 1

   Instead of:
   
#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
     _________________________________________________________________
   
4.4. Using Space

4.4.1. Put braces on a line by themselves.

   Explanation:
   
   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.
   
   Example:
if ( this == that )
{
   ...
}

   Instead of:
   
   if ( this == that ) { ... }
   
   or
   
   if ( this == that ) { ... }
   
   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.
   
   Status: developer-discrection.
   
   Example exception:
while ( more lines are read )
{
   /* Please document what is/is not a comment line here */
   if ( it's a comment ) continue;

   do_something( line );
}
     _________________________________________________________________
   
4.4.2. ALL control statements should have a block

   Explanation:
   
   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.
   
   Example:
if ( this == that )
{
   DoSomething();
   DoSomethingElse();
}

   Instead of:
   
   if ( this == that ) DoSomething(); DoSomethingElse();
   
   or
   
   if ( this == that ) DoSomething();
   
   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.
     _________________________________________________________________
   
4.4.3. Do not belabor/blow-up boolean expressions

   Example:
structure->flag = ( condition );

   Instead of:
   
   if ( condition ) { structure->flag = 1; } else { structure->flag = 0;
   }
   
   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-)
     _________________________________________________________________
   
4.4.4. Use white space freely because it is free

   Explanation:
   
   Make it readable. The notable exception to using white space freely is
   listed in the next guideline.
   
   Example:
int firstValue   = 0;
int someValue    = 0;
int anotherValue = 0;
int thisVariable = 0;

if ( thisVariable == thatVariable )

firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
     _________________________________________________________________
   
4.4.5. Don't use white space around structure operators

   Explanation:
   
   - structure pointer operator ( "->" ) - member operator ( "." ) -
   functions and parentheses
   
   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.
   
   Example:
aStruct->aMember;
aStruct.aMember;
FunctionName();

   Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();
     _________________________________________________________________
   
4.4.6. Make the last brace of a function stand out

   Example:
int function1( ... )
{
   ...code...
   return( retCode );

}   /* -END- function1 */


int function2( ... )
{
}   /* -END- function2 */

   Instead of:
   
   int function1( ... ) { ...code... return( retCode ); } int function2(
   ... ) { }
   
   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!
   
   Status: developer-discrection on the number of blank lines. Enforced
   is the end of function comments.
     _________________________________________________________________
   
4.4.7. Use 3 character indentions

   Explanation:
   
   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.
   
   Example:
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 );

}
     _________________________________________________________________
   
4.5. Initializing

4.5.1. Initialize all variables

   Explanation:
   
   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.
   
   Example:
short anShort = 0;
float aFloat  = 0;
struct *ptr = NULL;

   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].
   
   Status: developer-discrection if and only if the variable is assigned
   a value "shortly after" declaration.
     _________________________________________________________________
   
4.6. Functions

4.6.1. Name functions that return a boolean as a question.

   Explanation:
   
   Value should be phrased as a question that would logically be answered
   as a true or false statement
   
   Example:
ShouldWeBlockThis();
ContainsAnImage();
IsWebPageBlank();
     _________________________________________________________________
   
4.6.2. Always specify a return type for a function.

   Explanation:
   
   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.
     _________________________________________________________________
   
4.6.3. Minimize function calls when iterating by using variables

   Explanation:
   
   It is easy to write the following code, and a clear argument can be
   made that the code is easy to understand:
   
   Example:
for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
{
   ....
}

   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.
   
   Instead of using a function call during the iterations, assign the
   value to a variable, and evaluate using the variable.
   
   Example:
size_t len = blockListLength();

for ( size_t cnt = 0; cnt < len; cnt ++ )
{
   ....
}

   Exceptions: if the value of blockListLength() *may* change or could
   *potentially* change, then you must code the function call in the
   for/while loop.
     _________________________________________________________________
   
4.6.4. Pass and Return by Const Reference

   Explanation:
   
   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 );
   
   I could then not use it to compare argv's in main: int main( int argc,
   const char *argv[] ) { strcmp( argv[0], "privoxy" ); }
   
   Both these pointers are *const*! If the c runtime library maintainers
   do it, we should too.
     _________________________________________________________________
   
4.6.5. Pass and Return by Value

   Explanation:
   
   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 )
   
   would not work. So, to be consistent, we should declare all prototypes
   with "pass by value": int load_aclfile( struct client_state *csp )
     _________________________________________________________________
   
4.6.6. Names of include files

   Explanation:
   
   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.
   
   Example:
#include <iostream.h>     /* This is not a local include */
#include "config.h"       /* This IS a local include */

   Exception:
   
/* This is not a local include, but requires a path element. */
#include <sys/fileName.h>

   Note: Please! do not add "-I." to the Makefile without a _very_ good
   reason. This duplicates the #include "file.h" behaviour.
     _________________________________________________________________
   
4.6.7. Provide multiple inclusion protection

   Explanation:
   
   Prevents compiler and linker errors resulting from redefinition of
   items.
   
   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.
   
   Example:
#ifndef PROJECT_H_INCLUDED
#define PROJECT_H_INCLUDED
 ...
#endif /* ndef PROJECT_H_INCLUDED */
     _________________________________________________________________
   
4.6.8. Use `extern "C"` when appropriate

   Explanation:
   
   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.
   
   Example:
#ifdef __cplusplus
extern "C"
{
#endif /* def __cplusplus */

... function definitions here ...

#ifdef __cplusplus
}
#endif /* def __cplusplus */
     _________________________________________________________________
   
4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes

   Explanation:
   
   Useful in headers that include pointers to other struct's.
   Modifications to excess header files may cause needless compiles.
   
   Example:
/*********************************************************************
 * We're avoiding an include statement here!
 *********************************************************************/
struct file_list;
extern file_list *xyz;

   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.
   
   Status: Use with discrection.
     _________________________________________________________________
   
4.7. General Coding Practices

4.7.1. Turn on warnings

   Explanation
   
   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.
     _________________________________________________________________
   
4.7.2. Provide a default case for all switch statements

   Explanation:
   
   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.
   
   Example:
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 ) ) */

   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.
   
   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.
   
   Status: Programmer discretion is advised.
     _________________________________________________________________
   
4.7.3. Try to avoid falling through cases in a switch statement.

   Explanation:
   
   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.
   
   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.
   
   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.
     _________________________________________________________________
   
4.7.4. Use 'long' or 'short' Instead of 'int'

   Explanation:
   
   On 32-bit platforms, int usually has the range of long. On 16-bit
   platforms, int has the range of short.
   
   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?
     _________________________________________________________________
   
4.7.5. Don't mix size_t and other types

   Explanation:
   
   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.
     _________________________________________________________________
   
4.7.6. Declare each variable and struct on its own line.

   Explanation:
   
   It can be tempting to declare a series of variables all on one line.
   Don't.
   
   Example:
long a = 0;
long b = 0;
long c = 0;

   Instead of:
   
   long a, b, c;
   
   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
   
   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.
   
   Status: developer-discrection.
     _________________________________________________________________
   
4.7.7. Use malloc/zalloc sparingly

   Explanation:
   
   Create a local stuct (on the stack) if the variable will live and die
   within the context of one function call.
   
   Only "malloc" a struct (on the heap) if the variable's life will
   extend beyond the context of one function call.
   
   Example:
If a function creates a struct and stores a pointer to it in a
list, then it should definately be allocated via `malloc'.
     _________________________________________________________________
   
4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'

   Explanation:
   
   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.
   
   Example:
int load_re_filterfile( struct client_state *csp ) { ... }
static void unload_re_filterfile( void *f ) { ... }

   Exceptions:
   
   The developer cannot be expected to provide `free'ing functions for C
   run-time library functions ... such as `strdup'.
   
   Status: developer-discrection. The "main" use of this standard is for
   allocating and freeing data structures (complex or nested).
     _________________________________________________________________
   
4.7.9. Add loaders to the `file_list' structure and in order

   Explanation:
   
   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.
   
   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.
     _________________________________________________________________
   
4.7.10. "Uncertain" new code and/or changes to exitinst code, use FIXME

   Explanation:
   
   If you have enough confidence in new code or confidence in your
   changes, but are not *quite* sure of the reprocussions, add this:
   
   /* FIXME: this code has a logic error on platform XYZ, * attempthing
   to fix */ #ifdef PLATFORM ...changed code here... #endif
   
   or:
   
   /* FIXME: I think the original author really meant this... */
   ...changed code here...
   
   or:
   
   /* FIXME: new code that *may* break something else... */ ...new code
   here...
   
   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).
     _________________________________________________________________
   
4.8. Addendum: Template for files and function comment blocks:

   Example for file comments:
const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.13 2002/03/27 01:16
:41 hal9 Exp $";
/*********************************************************************
 *
 * File        :  $Source$
 *
 * Purpose     :  (Fill me in with a good description!)
 *
 * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
 *                Privoxy team. http://www.privoxy.org/
 *
 *                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   :
 *    $Log$
 *
 *********************************************************************/


#include "config.h"

   ...necessary include files for us to do our work...

const char FILENAME_h_rcs[] = FILENAME_H_VERSION;

   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.
   
   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.
   
   Example for file header comments:
#ifndef _FILENAME_H
#define _FILENAME_H
#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:
41 hal9 Exp $"
/*********************************************************************
 *
 * File        :  $Source$
 *
 * Purpose     :  (Fill me in with a good description!)
 *
 * Copyright   :  Written by and Copyright (C) 2001 the SourceForge
 *                Privoxy team. http://www.privoxy.org/
 *
 *                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   :
 *    $Log$
 *
 *********************************************************************/


#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:
*/

   Example for function comments:
/*********************************************************************
 *
 * 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 );

}

   Note: If we all follow this practice, we should be able to parse our
   code to create a "self-documenting" web page.
     _________________________________________________________________
   
5. Version Control Guidelines

   To be filled. note on cvs comments. don't comment what you did,
   comment why you did it.
     _________________________________________________________________
   
6. Testing Guidelines

   To be filled.
     _________________________________________________________________
   
6.1. Testplan for releases

   Explain release numbers. major, minor. developer releases. etc.
   
    1. Remove any existing rpm with rpm -e
    2. Remove any file that was left over. This includes (but is not
       limited to)
          + /var/log/privoxy
          + /etc/privoxy
          + /usr/sbin/privoxy
          + /etc/init.d/privoxy
          + /usr/doc/privoxy*
    3. Install the rpm. Any error messages?
    4. start,stop,status Privoxy with the specific script (e.g.
       /etc/rc.d/init/privoxy stop). Reboot your machine. Does autostart
       work?
    5. Start browsing. Does Privoxy work? Logfile written?
    6. Remove the rpm. Any error messages? All files removed?
     _________________________________________________________________
   
6.2. Test reports

   Please submit test reports only with the [59]test form at sourceforge.
   Three simple steps:
   
     * Select category: the distribution you test on.
     * Select group: the version of Privoxy that we are about to release.
     * Fill the Summary and Detailed Description with something
       intelligent (keep it short and precise).
       
   Do not mail to the mailinglist (we cannot keep track on issues there).
     _________________________________________________________________
   
7. Contact the developers

   Please see the user manual for information on how to contact the
   developers.
     _________________________________________________________________
   
8. Copyright and History

   Please see the user manual for information on Copyright and History.
     _________________________________________________________________
   
9. See also

   Please see the user manual for information on references.

References

   1. http://www.privoxy.org/developer-manual/
   2. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#INTRODUCTION
   3. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#QUICKSTART
   4. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#DOCUMENTATION
   5. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CODING
   6. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S1
   7. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S2
   8. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S3
   9. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S4
  10. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S5
  11. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S6
  12. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S7
  13. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S8
  14. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S9
  15. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S10
  16. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S11
  17. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S12
  18. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S13
  19. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S14
  20. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S15
  21. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S16
  22. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S17
  23. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S18
  24. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S19
  25. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S20
  26. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S21
  27. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S22
  28. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S23
  29. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S24
  30. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S25
  31. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S26
  32. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S27
  33. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S28
  34. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S29
  35. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S30
  36. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S31
  37. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S32
  38. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S33
  39. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S34
  40. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S35
  41. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S36
  42. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S37
  43. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S38
  44. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S39
  45. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S40
  46. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S41
  47. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S42
  48. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S43
  49. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S44
  50. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S45
  51. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S46
  52. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CVS
  53. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING
  54. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING-PLAN
  55. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING-REPORT
  56. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CONTACT
  57. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#COPYRIGHT
  58. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#SEEALSO
  59. http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005