2 Privoxy Developer Manual
6 $Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:41 hal9 Exp $
8 The developer manual gives the users information on how to help the
9 developer team. It provides guidance on coding, testing, documentation
12 Privoxy is a web proxy with advanced filtering capabilities for
13 protecting privacy, filtering web page content, managing cookies,
14 controlling access, and removing ads, banners, pop-ups and other
15 obnoxious Internet junk. Privoxy has a very flexible configuration and
16 can be customized to suit individual needs and tastes. Privoxy has
17 application for both stand-alone systems and multi-user networks.
19 Privoxy is based on the code of the Internet Junkbuster. Junkbuster
20 was originally written by JunkBusters Corporation, and was released as
21 free open-source software under the GNU GPL. Stefan Waldherr made many
22 improvements, and started the SourceForge project to continue
23 development. Other developers have since joined Stefan.
25 You can find the latest version of the user manual at
26 [1]http://www.privoxy.org/developer-manual/. Please see the Contact
27 section in the user-manual if you want to contact the developers.
28 _________________________________________________________________
32 2. [3]Quickstart to Privoxy Development
33 3. [4]Documentation Guidelines
34 4. [5]Coding Guidelines
37 4.2. [7]Using Comments
39 4.2.1. [8]Comment, Comment, Comment
40 4.2.2. [9]Use blocks for comments
41 4.2.3. [10]Keep Comments on their own line
42 4.2.4. [11]Comment each logical step
43 4.2.5. [12]Comment All Functions Thoroughly
44 4.2.6. [13]Comment at the end of braces if the content is
45 more than one screen length
47 4.3. [14]Naming Conventions
49 4.3.1. [15]Variable Names
50 4.3.2. [16]Function Names
51 4.3.3. [17]Header file prototypes
52 4.3.4. [18]Enumerations, and #defines
57 4.4.1. [21]Put braces on a line by themselves.
58 4.4.2. [22]ALL control statements should have a block
59 4.4.3. [23]Do not belabor/blow-up boolean expressions
60 4.4.4. [24]Use white space freely because it is free
61 4.4.5. [25]Don't use white space around structure operators
62 4.4.6. [26]Make the last brace of a function stand out
63 4.4.7. [27]Use 3 character indentions
67 4.5.1. [29]Initialize all variables
71 4.6.1. [31]Name functions that return a boolean as a
74 4.6.2. [32]Always specify a return type for a function.
75 4.6.3. [33]Minimize function calls when iterating by using
78 4.6.4. [34]Pass and Return by Const Reference
79 4.6.5. [35]Pass and Return by Value
80 4.6.6. [36]Names of include files
81 4.6.7. [37]Provide multiple inclusion protection
82 4.6.8. [38]Use `extern "C"` when appropriate
83 4.6.9. [39]Where Possible, Use Forward Struct Declaration
86 4.7. [40]General Coding Practices
88 4.7.1. [41]Turn on warnings
89 4.7.2. [42]Provide a default case for all switch statements
90 4.7.3. [43]Try to avoid falling through cases in a switch
93 4.7.4. [44]Use 'long' or 'short' Instead of 'int'
94 4.7.5. [45]Don't mix size_t and other types
95 4.7.6. [46]Declare each variable and struct on its own
98 4.7.7. [47]Use malloc/zalloc sparingly
99 4.7.8. [48]The Programmer Who Uses 'malloc' is Responsible
102 4.7.9. [49]Add loaders to the `file_list' structure and in
105 4.7.10. [50]"Uncertain" new code and/or changes to exitinst
108 4.8. [51]Addendum: Template for files and function comment
111 5. [52]Version Control Guidelines
112 6. [53]Testing Guidelines
114 6.1. [54]Testplan for releases
115 6.2. [55]Test reports
117 7. [56]Contact the developers
118 8. [57]Copyright and History
124 _________________________________________________________________
126 2. Quickstart to Privoxy Development
128 You'll need an account on Sourceforge to support our development. Mail
129 you ID to the list and wait until a project manager has added you. For
130 the time beeing (read, this section is under construction), please
131 note the following guidelines for changing stuff in the code. If it is
133 1. A bugfix / clean-up / cosmetic thing: shoot
134 2. A new feature that can be turned off: shoot
135 3. A clear improvement w/o side effects on other parts of the code:
137 4. A matter of taste: ask the list
138 5. A major redesign of some part of the code: ask the list
139 _________________________________________________________________
141 3. Documentation Guidelines
143 All docs are in SGML format and located in the doc/source directory.
145 How do you update the webserver (i.e. the pages on sourceforge)?
147 1. Run make dok (which uses the documents in doc/source to update all
148 text files in doc/text and to update all web documents in
150 2. Run make webserver which copies all files from doc/webserver to
151 the sourceforge webserver via scp.
152 _________________________________________________________________
158 This set of standards is designed to make our lives easier. It is
159 developed with the simple goal of helping us keep the "new and
160 improved Privoxy" consistent and reliable. Thus making maintenance
161 easier and increasing chances of success of the project.
163 And that of course comes back to us as individuals. If we can increase
164 our development and product efficiencies then we can solve more of the
165 request for changes/improvements and in general feel good about
167 _________________________________________________________________
171 4.2.1. Comment, Comment, Comment
175 Comment as much as possible without commenting the obvious. For
176 example do not comment "aVariable is equal to bVariable". Instead
177 explain why aVariable should be equal to the bVariable. Just because a
178 person can read code does not mean they will understand why or what is
179 being done. A reader may spend a lot more time figuring out what is
180 going on when a simple comment or explanation would have prevented the
181 extra research. Please help your brother IJB'ers out!
183 The comments will also help justify the intent of the code. If the
184 comment describes something different than what the code is doing then
185 maybe a programming error is occurring.
188 /* if page size greater than 1k ... */
189 if ( PageLength() > 1024 )
191 ... "block" the page up ...
194 /* if page size is small, send it in blocks */
195 if ( PageLength() > 1024 )
197 ... "block" the page up ...
200 This demonstrates 2 cases of "what not to do". The first is a
201 "syntax comment". The second is a comment that does not fit what
202 is actually being done.
203 _________________________________________________________________
205 4.2.2. Use blocks for comments
209 Comments can help or they can clutter. They help when they are
210 differentiated from the code they describe. One line comments do not
211 offer effective separation between the comment and the code. Block
212 identifiers do, by surrounding the code with a clear, definable
216 /*********************************************************************
217 * This will stand out clearly in your code!
218 *********************************************************************/
219 if ( thisVariable == thatVariable )
221 DoSomethingVeryImportant();
225 /* unfortunately, this may not */
226 if ( thisVariable == thatVariable )
228 DoSomethingVeryImportant();
232 if ( thisVariable == thatVariable ) /* this may not either */
234 DoSomethingVeryImportant();
239 If you are trying to add a small logic comment and do not wish to
240 "disrubt" the flow of the code, feel free to use a 1 line comment
241 which is NOT on the same line as the code.
242 _________________________________________________________________
244 4.2.3. Keep Comments on their own line
248 It goes back to the question of readability. If the comment is on the
249 same line as the code it will be harder to read than the comment that
252 There are three exceptions to this rule, which should be violated
253 freely and often: during the definition of variables, at the end of
254 closing braces, when used to comment parameters.
257 /*********************************************************************
258 * This will stand out clearly in your code,
259 * But the second example won't.
260 *********************************************************************/
261 if ( thisVariable == thatVariable )
263 DoSomethingVeryImportant();
266 if ( thisVariable == thatVariable ) /*can you see me?*/
268 DoSomethingVeryImportant(); /*not easily*/
272 /*********************************************************************
273 * But, the encouraged exceptions:
274 *********************************************************************/
275 int urls_read = 0; /* # of urls read + rejected */
276 int urls_rejected = 0; /* # of urls rejected */
280 DoSomethingVeryImportant();
284 short DoSomethingVeryImportant(
285 short firstparam, /* represents something */
286 short nextparam /* represents something else */ )
290 } /* -END- DoSomethingVeryImportant */
291 _________________________________________________________________
293 4.2.4. Comment each logical step
297 Logical steps should be commented to help others follow the intent of
298 the written code and comments will make the code more readable.
300 If you have 25 lines of code without a comment, you should probably go
301 back into it to see where you forgot to put one.
303 Most "for", "while", "do", etc... loops _probably_ need a comment.
304 After all, these are usually major logic containers.
305 _________________________________________________________________
307 4.2.5. Comment All Functions Thoroughly
311 A reader of the code should be able to look at the comments just prior
312 to the beginning of a function and discern the reason for its
313 existence and the consequences of using it. The reader should not have
314 to read through the code to determine if a given function is safe for
315 a desired use. The proper information thoroughly presented at the
316 introduction of a function not only saves time for subsequent
317 maintenance or debugging, it more importantly aids in code reuse by
318 allowing a user to determine the safety and applicability of any
319 function for the problem at hand. As a result of such benefits, all
320 functions should contain the information presented in the addendum
321 section of this document.
322 _________________________________________________________________
324 4.2.6. Comment at the end of braces if the content is more than one screen
329 Each closing brace should be followed on the same line by a comment
330 that describes the origination of the brace if the original brace is
331 off of the screen, or otherwise far away from the closing brace. This
332 will simplify the debugging, maintenance, and readability of the code.
334 As a suggestion , use the following flags to make the comment and its
337 use following a closing brace: } /* -END- if() or while () or etc...
343 DoSomethingVeryImportant();
344 ...some long list of commands...
345 } /* -END- if x is 1 */
351 DoSomethingVeryImportant();
352 ...some long list of commands...
353 } /* -END- if ( 1 == X ) */
354 _________________________________________________________________
356 4.3. Naming Conventions
358 4.3.1. Variable Names
362 Use all lowercase, and seperate words via an underscore ('_'). Do not
363 start an identifier with an underscore. (ANSI C reserves these for use
364 by the compiler and system headers.) Do not use identifiers which are
365 reserved in ANSI C++. (E.g. template, class, true, false, ...). This
366 is in case we ever decide to port Privoxy to C++.
369 int ms_iis5_hack = 0;
373 int msiis5hack = 0; int msIis5Hack = 0;
374 _________________________________________________________________
376 4.3.2. Function Names
380 Use all lowercase, and seperate words via an underscore ('_'). Do not
381 start an identifier with an underscore. (ANSI C reserves these for use
382 by the compiler and system headers.) Do not use identifiers which are
383 reserved in ANSI C++. (E.g. template, class, true, false, ...). This
384 is in case we ever decide to port Privoxy to C++.
387 int load_some_file( struct client_state *csp )
391 int loadsomefile( struct client_state *csp )
392 int loadSomeFile( struct client_state *csp )
393 _________________________________________________________________
395 4.3.3. Header file prototypes
399 Use a descriptive parameter name in the function prototype in header
400 files. Use the same parameter name in the header file that you use in
404 (.h) extern int load_aclfile( struct client_state *csp );
405 (.c) int load_aclfile( struct client_state *csp )
408 (.h) extern int load_aclfile( struct client_state * ); or
409 (.h) extern int load_aclfile();
410 (.c) int load_aclfile( struct client_state *csp )
411 _________________________________________________________________
413 4.3.4. Enumerations, and #defines
417 Use all capital letters, with underscores between words. Do not start
418 an identifier with an underscore. (ANSI C reserves these for use by
419 the compiler and system headers.)
422 (enumeration) : enum Boolean { FALSE, TRUE };
423 (#define) : #define DEFAULT_SIZE 100;
425 Note: We have a standard naming scheme for #defines that toggle a
426 feature in the preprocessor: FEATURE_>, where > is a short (preferably
427 1 or 2 word) description.
430 #define FEATURE_FORCE 1
433 #define FORCE_PREFIX blah
434 #endif /* def FEATURE_FORCE */
435 _________________________________________________________________
441 Spell common words out entirely (do not remove vowels).
443 Use only widely-known domain acronyms and abbreviations. Capitalize
444 all letters of an acronym.
446 Use underscore (_) to separate adjacent acronyms and abbreviations.
447 Never terminate a name with an underscore.
450 #define USE_IMAGE_LIST 1
454 #define USE_IMG_LST 1 or
455 #define _USE_IMAGE_LIST 1 or
456 #define USE_IMAGE_LIST_ 1 or
457 #define use_image_list 1 or
458 #define UseImageList 1
459 _________________________________________________________________
463 4.4.1. Put braces on a line by themselves.
467 The brace needs to be on a line all by itself, not at the end of the
468 statement. Curly braces should line up with the construct that they're
469 associated with. This practice makes it easier to identify the opening
470 and closing braces for a block.
480 if ( this == that ) { ... }
484 if ( this == that ) { ... }
486 Note: In the special case that the if-statement is inside a loop, and
487 it is trivial, i.e. it tests for a condidtion that is obvious from the
488 purpose of the block, one-liners as above may optically preserve the
489 loop structure and make it easier to read.
491 Status: developer-discrection.
494 while ( more lines are read )
496 /* Please document what is/is not a comment line here */
497 if ( it's a comment ) continue;
499 do_something( line );
501 _________________________________________________________________
503 4.4.2. ALL control statements should have a block
507 Using braces to make a block will make your code more readable and
508 less prone to error. All control statements should have a block
520 if ( this == that ) DoSomething(); DoSomethingElse();
524 if ( this == that ) DoSomething();
526 Note: The first example in "Instead of" will execute in a manner other
527 than that which the developer desired (per indentation). Using code
528 braces would have prevented this "feature". The "explanation" and
529 "exception" from the point above also applies.
530 _________________________________________________________________
532 4.4.3. Do not belabor/blow-up boolean expressions
535 structure->flag = ( condition );
539 if ( condition ) { structure->flag = 1; } else { structure->flag = 0;
542 Note: The former is readable and consice. The later is wordy and
543 inefficient. Please assume that any developer new to the project has
544 at least a "good" knowledge of C/C++. (Hope I do not offend by that
546 _________________________________________________________________
548 4.4.4. Use white space freely because it is free
552 Make it readable. The notable exception to using white space freely is
553 listed in the next guideline.
558 int anotherValue = 0;
559 int thisVariable = 0;
561 if ( thisVariable == thatVariable )
563 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
564 _________________________________________________________________
566 4.4.5. Don't use white space around structure operators
570 - structure pointer operator ( "->" ) - member operator ( "." ) -
571 functions and parentheses
573 It is a general coding practice to put pointers, references, and
574 function parentheses next to names. With spaces, the connection
575 between the object and variable/function name is not as clear.
582 Instead of: aStruct -> aMember; aStruct . aMember; FunctionName ();
583 _________________________________________________________________
585 4.4.6. Make the last brace of a function stand out
593 } /* -END- function1 */
598 } /* -END- function2 */
602 int function1( ... ) { ...code... return( retCode ); } int function2(
605 Note: Use 1 blank line before the closing brace and 2 lines
606 afterwards. This makes the end of function standout to the most casual
607 viewer. Although function comments help seperate functions, this is
608 still a good coding practice. In fact, I follow these rules when using
609 blocks in "for", "while", "do" loops, and long if {} statements too.
610 After all whitespace is free!
612 Status: developer-discrection on the number of blank lines. Enforced
613 is the end of function comments.
614 _________________________________________________________________
616 4.4.7. Use 3 character indentions
620 If some use 8 character TABs and some use 3 character TABs, the code
621 can look *very* ragged. So use 3 character indentions only. If you
622 like to use TABs, pass your code through a filter such as "expand -t3"
623 before checking in your code.
626 static const char * const url_code_map[256] =
636 return( ALWAYS_TRUE );
640 return( HOW_DID_YOU_GET_HERE );
643 return( NEVER_GETS_HERE );
646 _________________________________________________________________
650 4.5.1. Initialize all variables
654 Do not assume that the variables declared will not be used until after
655 they have been assigned a value somewhere else in the code. Remove the
656 chance of accidentally using an unassigned variable.
663 Note: It is much easier to debug a SIGSEGV if the message says you are
664 trying to access memory address 00000000 and not 129FA012; or
665 arrayPtr[20] causes a SIGSEV vs. arrayPtr[0].
667 Status: developer-discrection if and only if the variable is assigned
668 a value "shortly after" declaration.
669 _________________________________________________________________
673 4.6.1. Name functions that return a boolean as a question.
677 Value should be phrased as a question that would logically be answered
678 as a true or false statement
684 _________________________________________________________________
686 4.6.2. Always specify a return type for a function.
690 The default return for a function is an int. To avoid ambiguity,
691 create a return for a function when the return has a purpose, and
692 create a void return type if the function does not need to return
694 _________________________________________________________________
696 4.6.3. Minimize function calls when iterating by using variables
700 It is easy to write the following code, and a clear argument can be
701 made that the code is easy to understand:
704 for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
709 Note: Unfortunately, this makes a function call for each and every
710 iteration. This increases the overhead in the program, because the
711 compiler has to look up the function each time, call it, and return a
712 value. Depending on what occurs in the blockListLength() call, it
713 might even be creating and destroying structures with each iteration,
714 even though in each case it is comparing "cnt" to the same value, over
715 and over. Remember too - even a call to blockListLength() is a
716 function call, with the same overhead.
718 Instead of using a function call during the iterations, assign the
719 value to a variable, and evaluate using the variable.
722 size_t len = blockListLength();
724 for ( size_t cnt = 0; cnt < len; cnt ++ )
729 Exceptions: if the value of blockListLength() *may* change or could
730 *potentially* change, then you must code the function call in the
732 _________________________________________________________________
734 4.6.4. Pass and Return by Const Reference
738 This allows a developer to define a const pointer and call your
739 function. If your function does not have the const keyword, we may not
740 be able to use your function. Consider strcmp, if it were defined as:
741 extern int strcmp( char *s1, char *s2 );
743 I could then not use it to compare argv's in main: int main( int argc,
744 const char *argv[] ) { strcmp( argv[0], "privoxy" ); }
746 Both these pointers are *const*! If the c runtime library maintainers
747 do it, we should too.
748 _________________________________________________________________
750 4.6.5. Pass and Return by Value
754 Most structures cannot fit onto a normal stack entry (i.e. they are
755 not 4 bytes or less). Aka, a function declaration like: int
756 load_aclfile( struct client_state csp )
758 would not work. So, to be consistent, we should declare all prototypes
759 with "pass by value": int load_aclfile( struct client_state *csp )
760 _________________________________________________________________
762 4.6.6. Names of include files
766 Your include statements should contain the file name without a path.
767 The path should be listed in the Makefile, using -I as processor
768 directive to search the indicated paths. An exception to this would be
769 for some proprietary software that utilizes a partial path to
770 distinguish their header files from system or other header files.
773 #include <iostream.h> /* This is not a local include */
774 #include "config.h" /* This IS a local include */
778 /* This is not a local include, but requires a path element. */
779 #include <sys/fileName.h>
781 Note: Please! do not add "-I." to the Makefile without a _very_ good
782 reason. This duplicates the #include "file.h" behaviour.
783 _________________________________________________________________
785 4.6.7. Provide multiple inclusion protection
789 Prevents compiler and linker errors resulting from redefinition of
792 Wrap each header file with the following syntax to prevent multiple
793 inclusions of the file. Of course, replace PROJECT_H with your file
794 name, with "." Changed to "_", and make it uppercase.
797 #ifndef PROJECT_H_INCLUDED
798 #define PROJECT_H_INCLUDED
800 #endif /* ndef PROJECT_H_INCLUDED */
801 _________________________________________________________________
803 4.6.8. Use `extern "C"` when appropriate
807 If our headers are included from C++, they must declare our functions
808 as `extern "C"`. This has no cost in C, but increases the potential
809 re-usability of our code.
815 #endif /* def __cplusplus */
817 ... function definitions here ...
821 #endif /* def __cplusplus */
822 _________________________________________________________________
824 4.6.9. Where Possible, Use Forward Struct Declaration Instead of Includes
828 Useful in headers that include pointers to other struct's.
829 Modifications to excess header files may cause needless compiles.
832 /*********************************************************************
833 * We're avoiding an include statement here!
834 *********************************************************************/
836 extern file_list *xyz;
838 Note: If you declare "file_list xyz;" (without the pointer), then
839 including the proper header file is necessary. If you only want to
840 prototype a pointer, however, the header file is unneccessary.
842 Status: Use with discrection.
843 _________________________________________________________________
845 4.7. General Coding Practices
847 4.7.1. Turn on warnings
851 Compiler warnings are meant to help you find bugs. You should turn on
852 as many as possible. With GCC, the switch is "-Wall". Try and fix as
853 many warnings as possible.
854 _________________________________________________________________
856 4.7.2. Provide a default case for all switch statements
860 What you think is guaranteed is never really guaranteed. The value
861 that you don't think you need to check is the one that someday will be
862 passed. So, to protect yourself from the unknown, always have a
863 default step in a switch statement.
866 switch( hash_string( cmd ) )
868 case hash_actions_file :
878 ... anomly code goes here ...
879 continue; / break; / exit( 1 ); / etc ...
881 } /* end switch( hash_string( cmd ) ) */
883 Note: If you already have a default condition, you are obviously
884 exempt from this point. Of note, most of the WIN32 code calls
885 `DefWindowProc' after the switch statement. This API call *should* be
886 included in a default statement.
888 Another Note: This is not so much a readability issue as a robust
889 programming issue. The "anomly code goes here" may be no more than a
890 print to the STDERR stream (as in load_config). Or it may really be an
893 Status: Programmer discretion is advised.
894 _________________________________________________________________
896 4.7.3. Try to avoid falling through cases in a switch statement.
900 In general, you will want to have a 'break' statement within each
901 'case' of a switch statement. This allows for the code to be more
902 readable and understandable, and furthermore can prevent unwanted
903 surprises if someone else later gets creative and moves the code
906 The language allows you to plan the fall through from one case
907 statement to another simply by omitting the break statement within the
908 case statement. This feature does have benefits, but should only be
909 used in rare cases. In general, use a break statement for each case
912 If you choose to allow fall through, you should comment both the fact
913 of the fall through and reason why you felt it was necessary.
914 _________________________________________________________________
916 4.7.4. Use 'long' or 'short' Instead of 'int'
920 On 32-bit platforms, int usually has the range of long. On 16-bit
921 platforms, int has the range of short.
923 Status: open-to-debate. In the case of most FSF projects (including
924 X/GNU-Emacs), there are typedefs to int4, int8, int16, (or equivalence
925 ... I forget the exact typedefs now). Should we add these to IJB now
926 that we have a "configure" script?
927 _________________________________________________________________
929 4.7.5. Don't mix size_t and other types
933 The type of size_t varies across platforms. Do not make assumptions
934 about whether it is signed or unsigned, or about how long it is. Do
935 not compare a size_t against another variable of a different type (or
936 even against a constant) without casting one of the values. Try to
937 avoid using size_t if you can.
938 _________________________________________________________________
940 4.7.6. Declare each variable and struct on its own line.
944 It can be tempting to declare a series of variables all on one line.
956 Explanation: - there is more room for comments on the individual
957 variables - easier to add new variables without messing up the
958 original ones - when searching on a variable to find its type, there
959 is less clutter to "visually" eliminate
961 Exceptions: when you want to declare a bunch of loop variables or
962 other trivial variables; feel free to declare them on 1 line. You
963 should, although, provide a good comment on their functions.
965 Status: developer-discrection.
966 _________________________________________________________________
968 4.7.7. Use malloc/zalloc sparingly
972 Create a local stuct (on the stack) if the variable will live and die
973 within the context of one function call.
975 Only "malloc" a struct (on the heap) if the variable's life will
976 extend beyond the context of one function call.
979 If a function creates a struct and stores a pointer to it in a
980 list, then it should definately be allocated via `malloc'.
981 _________________________________________________________________
983 4.7.8. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free'
987 If you have to "malloc" an instance, you are responsible for insuring
988 that the instance is `free'd, even if the deallocation event falls
989 within some other programmer's code. You are also responsible for
990 ensuring that deletion is timely (i.e. not too soon, not too late).
991 This is known as "low-coupling" and is a "good thing (tm)". You may
992 need to offer a free/unload/destuctor type function to accomodate
996 int load_re_filterfile( struct client_state *csp ) { ... }
997 static void unload_re_filterfile( void *f ) { ... }
1001 The developer cannot be expected to provide `free'ing functions for C
1002 run-time library functions ... such as `strdup'.
1004 Status: developer-discrection. The "main" use of this standard is for
1005 allocating and freeing data structures (complex or nested).
1006 _________________________________________________________________
1008 4.7.9. Add loaders to the `file_list' structure and in order
1012 I have ordered all of the "blocker" file code to be in alpha order. It
1013 is easier to add/read new blockers when you expect a certain order.
1015 Note: It may appear that the alpha order is broken in places by POPUP
1016 tests coming before PCRS tests. But since POPUPs can also be referred
1017 to as KILLPOPUPs, it is clear that it should come first.
1018 _________________________________________________________________
1020 4.7.10. "Uncertain" new code and/or changes to exitinst code, use FIXME
1024 If you have enough confidence in new code or confidence in your
1025 changes, but are not *quite* sure of the reprocussions, add this:
1027 /* FIXME: this code has a logic error on platform XYZ, * attempthing
1028 to fix */ #ifdef PLATFORM ...changed code here... #endif
1032 /* FIXME: I think the original author really meant this... */
1033 ...changed code here...
1037 /* FIXME: new code that *may* break something else... */ ...new code
1040 Note: If you make it clear that this may or may not be a "good thing
1041 (tm)", it will be easier to identify and include in the project (or
1042 conversly exclude from the project).
1043 _________________________________________________________________
1045 4.8. Addendum: Template for files and function comment blocks:
1047 Example for file comments:
1048 const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.13 2002/03/27 01:16
1050 /*********************************************************************
1054 * Purpose : (Fill me in with a good description!)
1056 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1057 * Privoxy team. http://www.privoxy.org/
1059 * Based on the Internet Junkbuster originally written
1060 * by and Copyright (C) 1997 Anonymous Coders and
1061 * Junkbusters Corporation. http://www.junkbusters.com
1063 * This program is free software; you can redistribute it
1064 * and/or modify it under the terms of the GNU General
1065 * Public License as published by the Free Software
1066 * Foundation; either version 2 of the License, or (at
1067 * your option) any later version.
1069 * This program is distributed in the hope that it will
1070 * be useful, but WITHOUT ANY WARRANTY; without even the
1071 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1072 * PARTICULAR PURPOSE. See the GNU General Public
1073 * License for more details.
1075 * The GNU General Public License should be included with
1076 * this file. If not, you can view it at
1077 * http://www.gnu.org/copyleft/gpl.html
1078 * or write to the Free Software Foundation, Inc., 59
1079 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1084 *********************************************************************/
1089 ...necessary include files for us to do our work...
1091 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1093 Note: This declares the rcs variables that should be added to the
1094 "show-proxy-args" page. If this is a brand new creation by you, you
1095 are free to change the "Copyright" section to represent the rights you
1098 Note: The formfeed character that is present right after the comment
1099 flower box is handy for (X|GNU)Emacs users to skip the verbige and get
1100 to the heart of the code (via `forward-page' and `backward-page').
1101 Please include it if you can.
1103 Example for file header comments:
1106 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.13 2002/03/27 01:16:
1108 /*********************************************************************
1112 * Purpose : (Fill me in with a good description!)
1114 * Copyright : Written by and Copyright (C) 2001 the SourceForge
1115 * Privoxy team. http://www.privoxy.org/
1117 * Based on the Internet Junkbuster originally written
1118 * by and Copyright (C) 1997 Anonymous Coders and
1119 * Junkbusters Corporation. http://www.junkbusters.com
1121 * This program is free software; you can redistribute it
1122 * and/or modify it under the terms of the GNU General
1123 * Public License as published by the Free Software
1124 * Foundation; either version 2 of the License, or (at
1125 * your option) any later version.
1127 * This program is distributed in the hope that it will
1128 * be useful, but WITHOUT ANY WARRANTY; without even the
1129 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1130 * PARTICULAR PURPOSE. See the GNU General Public
1131 * License for more details.
1133 * The GNU General Public License should be included with
1134 * this file. If not, you can view it at
1135 * http://www.gnu.org/copyleft/gpl.html
1136 * or write to the Free Software Foundation, Inc., 59
1137 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
1142 *********************************************************************/
1145 #include "project.h"
1151 ... function headers here ...
1154 /* Revision control strings from this header and associated .c file */
1155 extern const char FILENAME_rcs[];
1156 extern const char FILENAME_h_rcs[];
1163 #endif /* ndef _FILENAME_H */
1171 Example for function comments:
1172 /*********************************************************************
1174 * Function : FUNCTION_NAME
1176 * Description : (Fill me in with a good description!)
1179 * 1 : param1 = pointer to an important thing
1180 * 2 : x = pointer to something else
1182 * Returns : 0 => Ok, everything else is an error.
1184 *********************************************************************/
1185 int FUNCTION_NAME( void *param1, const char *x )
1192 Note: If we all follow this practice, we should be able to parse our
1193 code to create a "self-documenting" web page.
1194 _________________________________________________________________
1196 5. Version Control Guidelines
1198 To be filled. note on cvs comments. don't comment what you did,
1199 comment why you did it.
1200 _________________________________________________________________
1202 6. Testing Guidelines
1205 _________________________________________________________________
1207 6.1. Testplan for releases
1209 Explain release numbers. major, minor. developer releases. etc.
1211 1. Remove any existing rpm with rpm -e
1212 2. Remove any file that was left over. This includes (but is not
1217 + /etc/init.d/privoxy
1219 3. Install the rpm. Any error messages?
1220 4. start,stop,status Privoxy with the specific script (e.g.
1221 /etc/rc.d/init/privoxy stop). Reboot your machine. Does autostart
1223 5. Start browsing. Does Privoxy work? Logfile written?
1224 6. Remove the rpm. Any error messages? All files removed?
1225 _________________________________________________________________
1229 Please submit test reports only with the [59]test form at sourceforge.
1232 * Select category: the distribution you test on.
1233 * Select group: the version of Privoxy that we are about to release.
1234 * Fill the Summary and Detailed Description with something
1235 intelligent (keep it short and precise).
1237 Do not mail to the mailinglist (we cannot keep track on issues there).
1238 _________________________________________________________________
1240 7. Contact the developers
1242 Please see the user manual for information on how to contact the
1244 _________________________________________________________________
1246 8. Copyright and History
1248 Please see the user manual for information on Copyright and History.
1249 _________________________________________________________________
1253 Please see the user manual for information on references.
1257 1. http://www.privoxy.org/developer-manual/
1258 2. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#INTRODUCTION
1259 3. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#QUICKSTART
1260 4. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#DOCUMENTATION
1261 5. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CODING
1262 6. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S1
1263 7. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S2
1264 8. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S3
1265 9. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S4
1266 10. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S5
1267 11. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S6
1268 12. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S7
1269 13. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S8
1270 14. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S9
1271 15. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S10
1272 16. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S11
1273 17. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S12
1274 18. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S13
1275 19. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S14
1276 20. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S15
1277 21. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S16
1278 22. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S17
1279 23. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S18
1280 24. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S19
1281 25. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S20
1282 26. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S21
1283 27. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S22
1284 28. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S23
1285 29. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S24
1286 30. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S25
1287 31. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S26
1288 32. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S27
1289 33. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S28
1290 34. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S29
1291 35. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S30
1292 36. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S31
1293 37. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S32
1294 38. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S33
1295 39. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S34
1296 40. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S35
1297 41. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S36
1298 42. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S37
1299 43. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S38
1300 44. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S39
1301 45. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S40
1302 46. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S41
1303 47. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S42
1304 48. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S43
1305 49. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S44
1306 50. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S45
1307 51. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#S46
1308 52. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CVS
1309 53. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING
1310 54. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING-PLAN
1311 55. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#TESTING-REPORT
1312 56. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#CONTACT
1313 57. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#COPYRIGHT
1314 58. file://localhost/home/swa/sf/current-org/doc/source/tmp.html#SEEALSO
1315 59. http://sourceforge.net/tracker/?func=add&group_id=11118&atid=395005