1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
5 >Coding Guidelines</TITLE
8 CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
10 TITLE="Privoxy Developer Manual"
11 HREF="index.html"><LINK
13 TITLE="Documentation Guidelines"
14 HREF="documentation.html"><LINK
16 TITLE="Testing Guidelines"
17 HREF="testing.html"><LINK
20 HREF="../p_doc.css"><META
21 HTTP-EQUIV="Content-Type"
23 charset=ISO-8859-1"></HEAD
34 SUMMARY="Header navigation table"
43 >Privoxy Developer Manual</TH
51 HREF="documentation.html"
80 >4. Coding Guidelines</A
91 >This set of standards is designed to make our lives easier. It is
92 developed with the simple goal of helping us keep the "new and improved
96 >" consistent and reliable. Thus making
97 maintenance easier and increasing chances of success of the
100 >And that of course comes back to us as individuals. If we can
101 increase our development and product efficiencies then we can solve more
102 of the request for changes/improvements and in general feel good about
103 ourselves. ;-></P
111 >4.2. Using Comments</A
119 >4.2.1. Comment, Comment, Comment</A
130 >Comment as much as possible without commenting the obvious.
131 For example do not comment "variable_a is equal to variable_b".
132 Instead explain why variable_a should be equal to the variable_b.
133 Just because a person can read code does not mean they will
134 understand why or what is being done. A reader may spend a lot
135 more time figuring out what is going on when a simple comment
136 or explanation would have prevented the extra research. Please
137 help your brother IJB'ers out!</P
139 >The comments will also help justify the intent of the code.
140 If the comment describes something different than what the code
141 is doing then maybe a programming error is occurring.</P
157 CLASS="PROGRAMLISTING"
158 >/* if page size greater than 1k ... */
159 if ( page_length() > 1024 )
161 ... "block" the page up ...
164 /* if page size is small, send it in blocks */
165 if ( page_length() > 1024 )
167 ... "block" the page up ...
170 This demonstrates 2 cases of "what not to do". The first is a
171 "syntax comment". The second is a comment that does not fit what
172 is actually being done.</PRE
183 >4.2.2. Use blocks for comments</A
194 >Comments can help or they can clutter. They help when they
195 are differentiated from the code they describe. One line
196 comments do not offer effective separation between the comment
197 and the code. Block identifiers do, by surrounding the code
198 with a clear, definable pattern.</P
214 CLASS="PROGRAMLISTING"
215 >/*********************************************************************
216 * This will stand out clearly in your code!
217 *********************************************************************/
218 if ( this_variable == that_variable )
220 do_something_very_important();
224 /* unfortunately, this may not */
225 if ( this_variable == that_variable )
227 do_something_very_important();
231 if ( this_variable == that_variable ) /* this may not either */
233 do_something_very_important();
247 >If you are trying to add a small logic comment and do not
248 wish to "disrupt" the flow of the code, feel free to use a 1
249 line comment which is NOT on the same line as the code.</P
257 >4.2.3. Keep Comments on their own line</A
268 >It goes back to the question of readability. If the comment
269 is on the same line as the code it will be harder to read than
270 the comment that is on its own line.</P
272 >There are three exceptions to this rule, which should be
273 violated freely and often: during the definition of variables,
274 at the end of closing braces, when used to comment
291 CLASS="PROGRAMLISTING"
292 >/*********************************************************************
293 * This will stand out clearly in your code,
294 * But the second example won't.
295 *********************************************************************/
296 if ( this_variable == this_variable )
298 do_something_very_important();
301 if ( this_variable == this_variable ) /*can you see me?*/
303 do_something_very_important(); /*not easily*/
307 /*********************************************************************
308 * But, the encouraged exceptions:
309 *********************************************************************/
310 int urls_read = 0; /* # of urls read + rejected */
311 int urls_rejected = 0; /* # of urls rejected */
315 do_something_very_important();
319 short do_something_very_important(
320 short firstparam, /* represents something */
321 short nextparam /* represents something else */ )
325 } /* -END- do_something_very_important */</PRE
336 >4.2.4. Comment each logical step</A
347 >Logical steps should be commented to help others follow the
348 intent of the written code and comments will make the code more
351 >If you have 25 lines of code without a comment, you should
352 probably go back into it to see where you forgot to put
355 >Most "for", "while", "do", etc... loops _probably_ need a
356 comment. After all, these are usually major logic
365 >4.2.5. Comment All Functions Thoroughly</A
376 >A reader of the code should be able to look at the comments
377 just prior to the beginning of a function and discern the
378 reason for its existence and the consequences of using it. The
379 reader should not have to read through the code to determine if
380 a given function is safe for a desired use. The proper
381 information thoroughly presented at the introduction of a
382 function not only saves time for subsequent maintenance or
383 debugging, it more importantly aids in code reuse by allowing a
384 user to determine the safety and applicability of any function
385 for the problem at hand. As a result of such benefits, all
386 functions should contain the information presented in the
387 addendum section of this document.</P
395 >4.2.6. Comment at the end of braces if the
396 content is more than one screen length</A
407 >Each closing brace should be followed on the same line by a
408 comment that describes the origination of the brace if the
409 original brace is off of the screen, or otherwise far away from
410 the closing brace. This will simplify the debugging,
411 maintenance, and readability of the code.</P
413 >As a suggestion , use the following flags to make the
414 comment and its brace more readable:</P
416 >use following a closing brace: } /* -END- if() or while ()
433 CLASS="PROGRAMLISTING"
436 do_something_very_important();
437 ...some long list of commands...
438 } /* -END- if x is 1 */
444 do_something_very_important();
445 ...some long list of commands...
446 } /* -END- if ( 1 == X ) */</PRE
458 >4.3. Naming Conventions</A
466 >4.3.1. Variable Names</A
477 >Use all lowercase, and separate words via an underscore
478 ('_'). Do not start an identifier with an underscore. (ANSI C
479 reserves these for use by the compiler and system headers.) Do
480 not use identifiers which are reserved in ANSI C++. (E.g.
481 template, class, true, false, ...). This is in case we ever
482 decide to port Privoxy to C++.</P
498 CLASS="PROGRAMLISTING"
499 >int ms_iis5_hack = 0;</PRE
519 CLASS="PROGRAMLISTING"
520 >int msiis5hack = 0; int msIis5Hack = 0;</PRE
532 >4.3.2. Function Names</A
543 >Use all lowercase, and separate words via an underscore
544 ('_'). Do not start an identifier with an underscore. (ANSI C
545 reserves these for use by the compiler and system headers.) Do
546 not use identifiers which are reserved in ANSI C++. (E.g.
547 template, class, true, false, ...). This is in case we ever
548 decide to port Privoxy to C++.</P
564 CLASS="PROGRAMLISTING"
565 >int load_some_file( struct client_state *csp )</PRE
585 CLASS="PROGRAMLISTING"
586 >int loadsomefile( struct client_state *csp )
587 int loadSomeFile( struct client_state *csp )</PRE
599 >4.3.3. Header file prototypes</A
610 >Use a descriptive parameter name in the function prototype
611 in header files. Use the same parameter name in the header file
612 that you use in the c file.</P
628 CLASS="PROGRAMLISTING"
629 >(.h) extern int load_aclfile( struct client_state *csp );
630 (.c) int load_aclfile( struct client_state *csp )</PRE
649 CLASS="PROGRAMLISTING"
650 >(.h) extern int load_aclfile( struct client_state * ); or
651 (.h) extern int load_aclfile();
652 (.c) int load_aclfile( struct client_state *csp )</PRE
664 >4.3.4. Enumerations, and #defines</A
675 >Use all capital letters, with underscores between words. Do
676 not start an identifier with an underscore. (ANSI C reserves
677 these for use by the compiler and system headers.)</P
693 CLASS="PROGRAMLISTING"
694 >(enumeration) : enum Boolean { FALSE, TRUE };
695 (#define) : #define DEFAULT_SIZE 100;</PRE
706 > We have a standard naming scheme for #defines
707 that toggle a feature in the preprocessor: FEATURE_>, where
708 > is a short (preferably 1 or 2 word) description.</P
724 CLASS="PROGRAMLISTING"
725 >#define FEATURE_FORCE 1
728 #define FORCE_PREFIX blah
729 #endif /* def FEATURE_FORCE */</PRE
751 >Spell common words out entirely (do not remove vowels).</P
753 >Use only widely-known domain acronyms and abbreviations.
754 Capitalize all letters of an acronym.</P
756 >Use underscore (_) to separate adjacent acronyms and
757 abbreviations. Never terminate a name with an underscore.</P
773 CLASS="PROGRAMLISTING"
774 >#define USE_IMAGE_LIST 1</PRE
794 CLASS="PROGRAMLISTING"
795 >#define USE_IMG_LST 1 or
796 #define _USE_IMAGE_LIST 1 or
797 #define USE_IMAGE_LIST_ 1 or
798 #define use_image_list 1 or
799 #define UseImageList 1</PRE
820 >4.4.1. Put braces on a line by themselves.</A
831 >The brace needs to be on a line all by itself, not at the
832 end of the statement. Curly braces should line up with the
833 construct that they're associated with. This practice makes it
834 easier to identify the opening and closing braces for a
851 CLASS="PROGRAMLISTING"
868 >if ( this == that ) { ... }</P
872 >if ( this == that ) { ... }</P
880 > In the special case that the if-statement is
881 inside a loop, and it is trivial, i.e. it tests for a
882 condition that is obvious from the purpose of the block,
883 one-liners as above may optically preserve the loop structure
884 and make it easier to read.</P
892 > developer-discretion.</P
898 >Example exception:</I
908 CLASS="PROGRAMLISTING"
909 >while ( more lines are read )
911 /* Please document what is/is not a comment line here */
912 if ( it's a comment ) continue;
914 do_something( line );
926 >4.4.2. ALL control statements should have a
938 >Using braces to make a block will make your code more
939 readable and less prone to error. All control statements should
940 have a block defined.</P
956 CLASS="PROGRAMLISTING"
974 >if ( this == that ) do_something(); do_something_else();</P
978 >if ( this == that ) do_something();</P
986 > The first example in "Instead of" will execute
987 in a manner other than that which the developer desired (per
988 indentation). Using code braces would have prevented this
989 "feature". The "explanation" and "exception" from the point
990 above also applies.</P
998 >4.4.3. Do not belabor/blow-up boolean
1016 CLASS="PROGRAMLISTING"
1017 >structure->flag = ( condition );</PRE
1030 >if ( condition ) { structure->flag = 1; } else {
1031 structure->flag = 0; }</P
1039 > The former is readable and concise. The later
1040 is wordy and inefficient. Please assume that any developer new
1041 to the project has at least a "good" knowledge of C/C++. (Hope
1042 I do not offend by that last comment ... 8-)</P
1050 >4.4.4. Use white space freely because it is
1062 >Make it readable. The notable exception to using white space
1063 freely is listed in the next guideline.</P
1079 CLASS="PROGRAMLISTING"
1080 >int first_value = 0;
1082 int another_value = 0;
1083 int this_variable = 0;
1085 if ( this_variable == this_variable )
1087 first_value = old_value + ( ( some_value - another_value ) - whatever )</PRE
1098 >4.4.5. Don't use white space around structure
1110 >- structure pointer operator ( "->" ) - member operator (
1111 "." ) - functions and parentheses</P
1113 >It is a general coding practice to put pointers, references,
1114 and function parentheses next to names. With spaces, the
1115 connection between the object and variable/function name is not
1132 CLASS="PROGRAMLISTING"
1133 >a_struct->a_member;
1135 function_name();</PRE
1146 > a_struct -> a_member; a_struct . a_member;
1147 function_name ();</P
1155 >4.4.6. Make the last brace of a function stand
1173 CLASS="PROGRAMLISTING"
1174 >int function1( ... )
1179 } /* -END- function1 */
1182 int function2( ... )
1184 } /* -END- function2 */</PRE
1197 >int function1( ... ) { ...code... return( ret_code ); } int
1198 function2( ... ) { }</P
1206 > Use 1 blank line before the closing brace and 2
1207 lines afterward. This makes the end of function standout to
1208 the most casual viewer. Although function comments help
1209 separate functions, this is still a good coding practice. In
1210 fact, I follow these rules when using blocks in "for", "while",
1211 "do" loops, and long if {} statements too. After all whitespace
1220 > developer-discretion on the number of blank
1221 lines. Enforced is the end of function comments.</P
1229 >4.4.7. Use 3 character indentions</A
1240 >If some use 8 character TABs and some use 3 character TABs,
1241 the code can look *very* ragged. So use 3 character indentions
1242 only. If you like to use TABs, pass your code through a filter
1243 such as "expand -t3" before checking in your code.</P
1259 CLASS="PROGRAMLISTING"
1260 >static const char * const url_code_map[256] =
1266 int function1( ... )
1270 return( ALWAYS_TRUE );
1274 return( HOW_DID_YOU_GET_HERE );
1277 return( NEVER_GETS_HERE );
1291 >4.5. Initializing</A
1299 >4.5.1. Initialize all variables</A
1310 >Do not assume that the variables declared will not be used
1311 until after they have been assigned a value somewhere else in
1312 the code. Remove the chance of accidentally using an unassigned
1329 CLASS="PROGRAMLISTING"
1332 struct *ptr = NULL;</PRE
1343 > It is much easier to debug a SIGSEGV if the
1344 message says you are trying to access memory address 00000000
1345 and not 129FA012; or array_ptr[20] causes a SIGSEV vs.
1354 > developer-discretion if and only if the
1355 variable is assigned a value "shortly after" declaration.</P
1372 >4.6.1. Name functions that return a boolean as a
1384 >Value should be phrased as a question that would logically
1385 be answered as a true or false statement</P
1401 CLASS="PROGRAMLISTING"
1402 >should_we_block_this();
1403 contains_an_image();
1404 is_web_page_blank();</PRE
1415 >4.6.2. Always specify a return type for a
1427 >The default return for a function is an int. To avoid
1428 ambiguity, create a return for a function when the return has a
1429 purpose, and create a void return type if the function does not
1430 need to return anything.</P
1438 >4.6.3. Minimize function calls when iterating by
1450 >It is easy to write the following code, and a clear argument
1451 can be made that the code is easy to understand:</P
1467 CLASS="PROGRAMLISTING"
1468 >for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
1482 > Unfortunately, this makes a function call for
1483 each and every iteration. This increases the overhead in the
1484 program, because the compiler has to look up the function each
1485 time, call it, and return a value. Depending on what occurs in
1486 the block_list_length() call, it might even be creating and
1487 destroying structures with each iteration, even though in each
1488 case it is comparing "cnt" to the same value, over and over.
1489 Remember too - even a call to block_list_length() is a function
1490 call, with the same overhead.</P
1492 >Instead of using a function call during the iterations,
1493 assign the value to a variable, and evaluate using the
1510 CLASS="PROGRAMLISTING"
1511 >size_t len = block_list_length();
1513 for ( size_t cnt = 0; cnt < len; cnt++ )
1527 > if the value of block_list_length()
1528 *may* change or could *potentially* change, then you must code the
1529 function call in the for/while loop.</P
1537 >4.6.4. Pass and Return by Const Reference</A
1548 >This allows a developer to define a const pointer and call
1549 your function. If your function does not have the const
1550 keyword, we may not be able to use your function. Consider
1551 strcmp, if it were defined as: extern int strcmp( char *s1,
1554 >I could then not use it to compare argv's in main: int main(
1555 int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
1558 >Both these pointers are *const*! If the c runtime library
1559 maintainers do it, we should too.</P
1567 >4.6.5. Pass and Return by Value</A
1578 >Most structures cannot fit onto a normal stack entry (i.e.
1579 they are not 4 bytes or less). Aka, a function declaration
1580 like: int load_aclfile( struct client_state csp )</P
1582 >would not work. So, to be consistent, we should declare all
1583 prototypes with "pass by value": int load_aclfile( struct
1584 client_state *csp )</P
1592 >4.6.6. Names of include files</A
1603 >Your include statements should contain the file name without
1604 a path. The path should be listed in the Makefile, using -I as
1605 processor directive to search the indicated paths. An exception
1606 to this would be for some proprietary software that utilizes a
1607 partial path to distinguish their header files from system or
1608 other header files.</P
1624 CLASS="PROGRAMLISTING"
1625 >#include <iostream.h> /* This is not a local include */
1626 #include "config.h" /* This IS a local include */</PRE
1646 CLASS="PROGRAMLISTING"
1647 >/* This is not a local include, but requires a path element. */
1648 #include <sys/fileName.h></PRE
1660 > Please! do not add "-I." to the Makefile
1661 without a _very_ good reason. This duplicates the #include
1662 "file.h" behavior.</P
1670 >4.6.7. Provide multiple inclusion
1682 >Prevents compiler and linker errors resulting from
1683 redefinition of items.</P
1685 >Wrap each header file with the following syntax to prevent
1686 multiple inclusions of the file. Of course, replace PROJECT_H
1687 with your file name, with "." Changed to "_", and make it
1704 CLASS="PROGRAMLISTING"
1705 >#ifndef PROJECT_H_INCLUDED
1706 #define PROJECT_H_INCLUDED
1708 #endif /* ndef PROJECT_H_INCLUDED */</PRE
1719 >4.6.8. Use `extern "C"` when appropriate</A
1730 >If our headers are included from C++, they must declare our
1731 functions as `extern "C"`. This has no cost in C, but increases
1732 the potential re-usability of our code.</P
1748 CLASS="PROGRAMLISTING"
1752 #endif /* def __cplusplus */
1754 ... function definitions here ...
1758 #endif /* def __cplusplus */</PRE
1769 >4.6.9. Where Possible, Use Forward Struct
1770 Declaration Instead of Includes</A
1781 >Useful in headers that include pointers to other struct's.
1782 Modifications to excess header files may cause needless
1799 CLASS="PROGRAMLISTING"
1800 >/*********************************************************************
1801 * We're avoiding an include statement here!
1802 *********************************************************************/
1804 extern file_list *xyz;</PRE
1815 > If you declare "file_list xyz;" (without the
1816 pointer), then including the proper header file is necessary.
1817 If you only want to prototype a pointer, however, the header
1818 file is unnecessary.</P
1826 > Use with discretion.</P
1835 >4.7. General Coding Practices</A
1843 >4.7.1. Turn on warnings</A
1854 >Compiler warnings are meant to help you find bugs. You
1855 should turn on as many as possible. With GCC, the switch is
1856 "-Wall". Try and fix as many warnings as possible.</P
1864 >4.7.2. Provide a default case for all switch
1876 >What you think is guaranteed is never really guaranteed. The
1877 value that you don't think you need to check is the one that
1878 someday will be passed. So, to protect yourself from the
1879 unknown, always have a default step in a switch statement.</P
1895 CLASS="PROGRAMLISTING"
1896 >switch( hash_string( cmd ) )
1898 case hash_actions_file :
1908 ... anomaly code goes here ...
1909 continue; / break; / exit( 1 ); / etc ...
1911 } /* end switch( hash_string( cmd ) ) */</PRE
1922 > If you already have a default condition, you
1923 are obviously exempt from this point. Of note, most of the
1924 WIN32 code calls `DefWindowProc' after the switch statement.
1925 This API call *should* be included in a default statement.</P
1933 > This is not so much a readability issue
1934 as a robust programming issue. The "anomaly code goes here" may
1935 be no more than a print to the STDERR stream (as in
1936 load_config). Or it may really be an abort condition.</P
1944 > Programmer discretion is advised.</P
1952 >4.7.3. Try to avoid falling through cases in a
1953 switch statement.</A
1964 >In general, you will want to have a 'break' statement within
1965 each 'case' of a switch statement. This allows for the code to
1966 be more readable and understandable, and furthermore can
1967 prevent unwanted surprises if someone else later gets creative
1968 and moves the code around.</P
1970 >The language allows you to plan the fall through from one
1971 case statement to another simply by omitting the break
1972 statement within the case statement. This feature does have
1973 benefits, but should only be used in rare cases. In general,
1974 use a break statement for each case statement.</P
1976 >If you choose to allow fall through, you should comment both
1977 the fact of the fall through and reason why you felt it was
1986 >4.7.4. Use 'long' or 'short' Instead of
1998 >On 32-bit platforms, int usually has the range of long. On
1999 16-bit platforms, int has the range of short.</P
2007 > open-to-debate. In the case of most FSF
2008 projects (including X/GNU-Emacs), there are typedefs to int4,
2009 int8, int16, (or equivalence ... I forget the exact typedefs
2010 now). Should we add these to IJB now that we have a "configure"
2019 >4.7.5. Don't mix size_t and other types</A
2030 >The type of size_t varies across platforms. Do not make
2031 assumptions about whether it is signed or unsigned, or about
2032 how long it is. Do not compare a size_t against another
2033 variable of a different type (or even against a constant)
2034 without casting one of the values.</P
2042 >4.7.6. Declare each variable and struct on its
2054 >It can be tempting to declare a series of variables all on
2071 CLASS="PROGRAMLISTING"
2095 > - there is more room for comments on the
2096 individual variables - easier to add new variables without
2097 messing up the original ones - when searching on a variable to
2098 find its type, there is less clutter to "visually"
2107 > when you want to declare a bunch of loop
2108 variables or other trivial variables; feel free to declare them
2109 on one line. You should, although, provide a good comment on
2118 > developer-discretion.</P
2126 >4.7.7. Use malloc/zalloc sparingly</A
2137 >Create a local struct (on the stack) if the variable will
2138 live and die within the context of one function call.</P
2140 >Only "malloc" a struct (on the heap) if the variable's life
2141 will extend beyond the context of one function call.</P
2157 CLASS="PROGRAMLISTING"
2158 >If a function creates a struct and stores a pointer to it in a
2159 list, then it should definitely be allocated via `malloc'.</PRE
2170 >4.7.8. The Programmer Who Uses 'malloc' is
2171 Responsible for Ensuring 'free'</A
2182 >If you have to "malloc" an instance, you are responsible for
2183 insuring that the instance is `free'd, even if the deallocation
2184 event falls within some other programmer's code. You are also
2185 responsible for ensuring that deletion is timely (i.e. not too
2186 soon, not too late). This is known as "low-coupling" and is a
2187 "good thing (tm)". You may need to offer a
2188 free/unload/destructor type function to accommodate this.</P
2204 CLASS="PROGRAMLISTING"
2205 >int load_re_filterfile( struct client_state *csp ) { ... }
2206 static void unload_re_filterfile( void *f ) { ... }</PRE
2219 >The developer cannot be expected to provide `free'ing
2220 functions for C run-time library functions ... such as
2229 > developer-discretion. The "main" use of this
2230 standard is for allocating and freeing data structures (complex
2239 >4.7.9. Add loaders to the `file_list' structure
2251 >I have ordered all of the "blocker" file code to be in alpha
2252 order. It is easier to add/read new blockers when you expect a
2261 > It may appear that the alpha order is broken in
2262 places by POPUP tests coming before PCRS tests. But since
2263 POPUPs can also be referred to as KILLPOPUPs, it is clear that
2264 it should come first.</P
2272 >4.7.10. "Uncertain" new code and/or changes to
2273 existing code, use FIXME or XXX</A
2284 >If you have enough confidence in new code or confidence in
2285 your changes, but are not *quite* sure of the repercussions,
2288 >/* FIXME: this code has a logic error on platform XYZ, *
2289 attempting to fix */ #ifdef PLATFORM ...changed code here...
2294 >/* FIXME: I think the original author really meant this...
2295 */ ...changed code here...</P
2299 >/* FIXME: new code that *may* break something else... */
2300 ...new code here...</P
2308 > If you make it clear that this may or may not
2309 be a "good thing (tm)", it will be easier to identify and
2310 include in the project (or conversely exclude from the
2320 >4.8. Addendum: Template for files and function
2328 >Example for file comments:</I
2338 CLASS="PROGRAMLISTING"
2339 >const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.19 2008/05/12 11:13:33 fabiankeil Exp $";
2340 /*********************************************************************
2344 * Purpose : (Fill me in with a good description!)
2346 * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
2347 * Privoxy team. http://www.privoxy.org/
2349 * Based on the Internet Junkbuster originally written
2350 * by and Copyright (C) 1997 Anonymous Coders and
2351 * Junkbusters Corporation. http://www.junkbusters.com
2353 * This program is free software; you can redistribute it
2354 * and/or modify it under the terms of the GNU General
2355 * Public License as published by the Free Software
2356 * Foundation; either version 2 of the License, or (at
2357 * your option) any later version.
2359 * This program is distributed in the hope that it will
2360 * be useful, but WITHOUT ANY WARRANTY; without even the
2361 * implied warranty of MERCHANTABILITY or FITNESS FOR A
2362 * PARTICULAR PURPOSE. See the GNU General Public
2363 * License for more details.
2365 * The GNU General Public License should be included with
2366 * this file. If not, you can view it at
2367 * http://www.gnu.org/copyleft/gpl.html
2368 * or write to the Free Software Foundation, Inc.,
2369 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
2375 *********************************************************************/
2380 ...necessary include files for us to do our work...
2382 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;</PRE
2393 > This declares the rcs variables that should be
2394 added to the "show-proxy-args" page. If this is a brand new
2395 creation by you, you are free to change the "Copyright" section
2396 to represent the rights you wish to maintain.</P
2404 > The formfeed character that is present right
2405 after the comment flower box is handy for (X|GNU)Emacs users to
2406 skip the verbiage and get to the heart of the code (via
2407 `forward-page' and `backward-page'). Please include it if you
2414 >Example for file header comments:</I
2424 CLASS="PROGRAMLISTING"
2425 >#ifndef _FILENAME_H
2427 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.19 2008/05/12 11:13:33 fabiankeil Exp $"
2428 /*********************************************************************
2432 * Purpose : (Fill me in with a good description!)
2434 * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
2435 * Privoxy team. http://www.privoxy.org/
2437 * Based on the Internet Junkbuster originally written
2438 * by and Copyright (C) 1997 Anonymous Coders and
2439 * Junkbusters Corporation. http://www.junkbusters.com
2441 * This program is free software; you can redistribute it
2442 * and/or modify it under the terms of the GNU General
2443 * Public License as published by the Free Software
2444 * Foundation; either version 2 of the License, or (at
2445 * your option) any later version.
2447 * This program is distributed in the hope that it will
2448 * be useful, but WITHOUT ANY WARRANTY; without even the
2449 * implied warranty of MERCHANTABILITY or FITNESS FOR A
2450 * PARTICULAR PURPOSE. See the GNU General Public
2451 * License for more details.
2453 * The GNU General Public License should be included with
2454 * this file. If not, you can view it at
2455 * http://www.gnu.org/copyleft/gpl.html
2456 * or write to the Free Software Foundation, Inc.,
2457 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
2463 *********************************************************************/
2466 #include "project.h"
2472 ... function headers here ...
2475 /* Revision control strings from this header and associated .c file */
2476 extern const char FILENAME_rcs[];
2477 extern const char FILENAME_h_rcs[];
2484 #endif /* ndef _FILENAME_H */
2499 >Example for function comments:</I
2509 CLASS="PROGRAMLISTING"
2510 >/*********************************************************************
2512 * Function : FUNCTION_NAME
2514 * Description : (Fill me in with a good description!)
2517 * 1 : param1 = pointer to an important thing
2518 * 2 : x = pointer to something else
2520 * Returns : 0 => Ok, everything else is an error.
2522 *********************************************************************/
2523 int FUNCTION_NAME( void *param1, const char *x )
2539 > If we all follow this practice, we should be
2540 able to parse our code to create a "self-documenting" web
2549 SUMMARY="Footer navigation table"
2560 HREF="documentation.html"
2588 >Documentation Guidelines</TD
2598 >Testing Guidelines</TD
projects / privoxy.git / blob