+
+Junkbuster Developer Manual
+
+ By: Junkbuster Developers
+
+ $Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:48 swa 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. The Internet Junkbuster is an application that
+ provides privacy and security to the user of the world wide web.
+
+ You can find the latest version of the user manual at
+ [1]http://ijbswa.sourceforge.net/developer-manual/. Please see the
+ Contact section in the user-manual if you want to contact the
+ developers.
+
+ Feel free to send a note to the developers at
+ <[2]ijbswa-developers@lists.sourceforge.net>.
+ _________________________________________________________________
+
+ Table of Contents
+ 1. [3]Introduction
+ 2. [4]Quickstart to Junkbuster Development
+ 3. [5]Documentation Guidelines
+ 4. [6]Coding Guidelines
+
+ 4.1. [7]Introduction
+ 4.2. [8]Using Comments
+ 4.3. [9]Naming Conventions
+ 4.4. [10]Using Space
+ 4.5. [11]Initializing
+ 4.6. [12]Functions
+ 4.7. [13]General Coding Practices
+ 4.8. [14]Addendum: Template for files and function comment
+ blocks:
+
+ 5. [15]Version Control Guidelines
+ 6. [16]Testing Guidelines
+
+ 6.1. [17]Testplan for releases
+ 6.2. [18]Test reports
+
+ 7. [19]Contact the developers
+ 8. [20]Copyright and History
+ 9. [21]See also
+
+1. Introduction
+
+ To be filled.
+ _________________________________________________________________
+
+2. Quickstart to Junkbuster Development
+
+ To be filled.
+ _________________________________________________________________
+
+3. Documentation Guidelines
+
+ All docs should be ...
+
+ * in a format that is widely used. I propose HTML.
+ * we either
+ + generate man pages from the documentation (let's _NOT_ write
+ them manually), or
+ + we have a man page that points to the documentation (I
+ propose this option)
+ * have a consistent layout
+ * have a link to the latest version of the document (i.e. point to a
+ URL at sf)
+ * be consistent with the redirect script (i.e. the junkbuster
+ program points via the redirect URL at sf to valid end-points in
+ the document)
+ * started from scratch but recycle parts from the original
+ junkbuster documents
+ _________________________________________________________________
+
+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 Junkbusters" 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 JunkBuster 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 JunkBuster 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], "junkbusters" ); }
+
+ 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.4 2001/09/23 10:13:
+48 swa Exp $";
+/*********************************************************************
+ *
+ * File : $Source$
+ *
+ * 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 :
+ * $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.4 2001/09/23 10:13:4
+8 swa Exp $"
+/*********************************************************************
+ *
+ * File : $Source$
+ *
+ * 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 :
+ * $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/junkbuster
+ + /etc/junkbuster
+ + /usr/sbin/junkbuster
+ + /etc/init.d/junkbuster
+ + /usr/doc/junkbuster*
+ 3. Install the rpm. Any error messages?
+ 4. start,stop,status junkbuster with the specific script (e.g.
+ /etc/rc.d/init/junkbuster stop). Reboot your machine. Does
+ autostart work?
+ 5. Start browsing. Does the junkbuster work? Logfile written?
+ 6. Remove the rpm. Any error messages? All files removed?
+ _________________________________________________________________
+
+6.2. Test reports
+
+ Please submit test reports only with the [22]test form at sourceforge.
+ Three simple steps:
+
+ * Select category: the distribution you test on.
+ * Select group: the version of Junkbuster 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://ijbswa.sourceforge.net/developer-manual/
+ 2. mailto:ijbswa-developers@lists.sourceforge.net
+ 3. file://localhost/home/swa/sf/current/doc/source/tmp.html#INTRODUCTION
+ 4. file://localhost/home/swa/sf/current/doc/source/tmp.html#QUICKSTART
+ 5. file://localhost/home/swa/sf/current/doc/source/tmp.html#DOCUMENTATION
+ 6. file://localhost/home/swa/sf/current/doc/source/tmp.html#CODING
+ 7. file://localhost/home/swa/sf/current/doc/source/tmp.html#S1
+ 8. file://localhost/home/swa/sf/current/doc/source/tmp.html#S2
+ 9. file://localhost/home/swa/sf/current/doc/source/tmp.html#S9
+ 10. file://localhost/home/swa/sf/current/doc/source/tmp.html#S15
+ 11. file://localhost/home/swa/sf/current/doc/source/tmp.html#S23
+ 12. file://localhost/home/swa/sf/current/doc/source/tmp.html#S25
+ 13. file://localhost/home/swa/sf/current/doc/source/tmp.html#S35
+ 14. file://localhost/home/swa/sf/current/doc/source/tmp.html#S46
+ 15. file://localhost/home/swa/sf/current/doc/source/tmp.html#CVS
+ 16. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING
+ 17. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING-PLAN
+ 18. file://localhost/home/swa/sf/current/doc/source/tmp.html#TESTING-REPORT
+ 19. file://localhost/home/swa/sf/current/doc/source/tmp.html#CONTACT
+ 20. file://localhost/home/swa/sf/current/doc/source/tmp.html#COPYRIGHT
+ 21. file://localhost/home/swa/sf/current/doc/source/tmp.html#SEEALSO
+ 22. http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005
projects / privoxy.git / commitdiff