4 >Coding Guidelines</TITLE
7 CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
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"></HEAD
31 SUMMARY="Header navigation table"
40 >Privoxy Developer Manual</TH
48 HREF="documentation.html"
78 >4. Coding Guidelines</H1
86 >4.1. Introduction</H2
88 >This set of standards is designed to make our lives easier. It is
89 developed with the simple goal of helping us keep the "new and improved
93 >" consistent and reliable. Thus making
94 maintenance easier and increasing chances of success of the
97 >And that of course comes back to us as individuals. If we can
98 increase our development and product efficiencies then we can solve more
99 of the request for changes/improvements and in general feel good about
100 ourselves. ;-></P
109 >4.2. Using Comments</H2
117 >4.2.1. Comment, Comment, Comment</H3
127 >Comment as much as possible without commenting the obvious.
128 For example do not comment "aVariable is equal to bVariable".
129 Instead explain why aVariable should be equal to the bVariable.
130 Just because a person can read code does not mean they will
131 understand why or what is being done. A reader may spend a lot
132 more time figuring out what is going on when a simple comment
133 or explanation would have prevented the extra research. Please
134 help your brother IJB'ers out!</P
136 >The comments will also help justify the intent of the code.
137 If the comment describes something different than what the code
138 is doing then maybe a programming error is occurring.</P
154 CLASS="PROGRAMLISTING"
155 >/* if page size greater than 1k ... */
156 if ( PageLength() > 1024 )
158 ... "block" the page up ...
161 /* if page size is small, send it in blocks */
162 if ( PageLength() > 1024 )
164 ... "block" the page up ...
167 This demonstrates 2 cases of "what not to do". The first is a
168 "syntax comment". The second is a comment that does not fit what
169 is actually being done.</PRE
181 >4.2.2. Use blocks for comments</H3
191 >Comments can help or they can clutter. They help when they
192 are differentiated from the code they describe. One line
193 comments do not offer effective separation between the comment
194 and the code. Block identifiers do, by surrounding the code
195 with a clear, definable pattern.</P
211 CLASS="PROGRAMLISTING"
212 >/*********************************************************************
213 * This will stand out clearly in your code!
214 *********************************************************************/
215 if ( thisVariable == thatVariable )
217 DoSomethingVeryImportant();
221 /* unfortunately, this may not */
222 if ( thisVariable == thatVariable )
224 DoSomethingVeryImportant();
228 if ( thisVariable == thatVariable ) /* this may not either */
230 DoSomethingVeryImportant();
244 >If you are trying to add a small logic comment and do not
245 wish to "disrupt" the flow of the code, feel free to use a 1
246 line comment which is NOT on the same line as the code.</P
255 >4.2.3. Keep Comments on their own line</H3
265 >It goes back to the question of readability. If the comment
266 is on the same line as the code it will be harder to read than
267 the comment that is on its own line.</P
269 >There are three exceptions to this rule, which should be
270 violated freely and often: during the definition of variables,
271 at the end of closing braces, when used to comment
288 CLASS="PROGRAMLISTING"
289 >/*********************************************************************
290 * This will stand out clearly in your code,
291 * But the second example won't.
292 *********************************************************************/
293 if ( thisVariable == thatVariable )
295 DoSomethingVeryImportant();
298 if ( thisVariable == thatVariable ) /*can you see me?*/
300 DoSomethingVeryImportant(); /*not easily*/
304 /*********************************************************************
305 * But, the encouraged exceptions:
306 *********************************************************************/
307 int urls_read = 0; /* # of urls read + rejected */
308 int urls_rejected = 0; /* # of urls rejected */
312 DoSomethingVeryImportant();
316 short DoSomethingVeryImportant(
317 short firstparam, /* represents something */
318 short nextparam /* represents something else */ )
322 } /* -END- DoSomethingVeryImportant */</PRE
334 >4.2.4. Comment each logical step</H3
344 >Logical steps should be commented to help others follow the
345 intent of the written code and comments will make the code more
348 >If you have 25 lines of code without a comment, you should
349 probably go back into it to see where you forgot to put
352 >Most "for", "while", "do", etc... loops _probably_ need a
353 comment. After all, these are usually major logic
363 >4.2.5. Comment All Functions Thoroughly</H3
373 >A reader of the code should be able to look at the comments
374 just prior to the beginning of a function and discern the
375 reason for its existence and the consequences of using it. The
376 reader should not have to read through the code to determine if
377 a given function is safe for a desired use. The proper
378 information thoroughly presented at the introduction of a
379 function not only saves time for subsequent maintenance or
380 debugging, it more importantly aids in code reuse by allowing a
381 user to determine the safety and applicability of any function
382 for the problem at hand. As a result of such benefits, all
383 functions should contain the information presented in the
384 addendum section of this document.</P
393 >4.2.6. Comment at the end of braces if the
394 content is more than one screen length</H3
404 >Each closing brace should be followed on the same line by a
405 comment that describes the origination of the brace if the
406 original brace is off of the screen, or otherwise far away from
407 the closing brace. This will simplify the debugging,
408 maintenance, and readability of the code.</P
410 >As a suggestion , use the following flags to make the
411 comment and its brace more readable:</P
413 >use following a closing brace: } /* -END- if() or while ()
430 CLASS="PROGRAMLISTING"
433 DoSomethingVeryImportant();
434 ...some long list of commands...
435 } /* -END- if x is 1 */
441 DoSomethingVeryImportant();
442 ...some long list of commands...
443 } /* -END- if ( 1 == X ) */</PRE
456 >4.3. Naming Conventions</H2
464 >4.3.1. Variable Names</H3
474 >Use all lowercase, and separate words via an underscore
475 ('_'). Do not start an identifier with an underscore. (ANSI C
476 reserves these for use by the compiler and system headers.) Do
477 not use identifiers which are reserved in ANSI C++. (E.g.
478 template, class, true, false, ...). This is in case we ever
479 decide to port Privoxy to C++.</P
495 CLASS="PROGRAMLISTING"
496 >int ms_iis5_hack = 0;</PRE
516 CLASS="PROGRAMLISTING"
517 >int msiis5hack = 0; int msIis5Hack = 0;</PRE
530 >4.3.2. Function Names</H3
540 >Use all lowercase, and separate words via an underscore
541 ('_'). Do not start an identifier with an underscore. (ANSI C
542 reserves these for use by the compiler and system headers.) Do
543 not use identifiers which are reserved in ANSI C++. (E.g.
544 template, class, true, false, ...). This is in case we ever
545 decide to port Privoxy to C++.</P
561 CLASS="PROGRAMLISTING"
562 >int load_some_file( struct client_state *csp )</PRE
582 CLASS="PROGRAMLISTING"
583 >int loadsomefile( struct client_state *csp )
584 int loadSomeFile( struct client_state *csp )</PRE
597 >4.3.3. Header file prototypes</H3
607 >Use a descriptive parameter name in the function prototype
608 in header files. Use the same parameter name in the header file
609 that you use in the c file.</P
625 CLASS="PROGRAMLISTING"
626 >(.h) extern int load_aclfile( struct client_state *csp );
627 (.c) int load_aclfile( struct client_state *csp )</PRE
646 CLASS="PROGRAMLISTING"
647 >(.h) extern int load_aclfile( struct client_state * ); or
648 (.h) extern int load_aclfile();
649 (.c) int load_aclfile( struct client_state *csp )</PRE
662 >4.3.4. Enumerations, and #defines</H3
672 >Use all capital letters, with underscores between words. Do
673 not start an identifier with an underscore. (ANSI C reserves
674 these for use by the compiler and system headers.)</P
690 CLASS="PROGRAMLISTING"
691 >(enumeration) : enum Boolean { FALSE, TRUE };
692 (#define) : #define DEFAULT_SIZE 100;</PRE
703 > We have a standard naming scheme for #defines
704 that toggle a feature in the preprocessor: FEATURE_>, where
705 > is a short (preferably 1 or 2 word) description.</P
721 CLASS="PROGRAMLISTING"
722 >#define FEATURE_FORCE 1
725 #define FORCE_PREFIX blah
726 #endif /* def FEATURE_FORCE */</PRE
738 >4.3.5. Constants</H3
748 >Spell common words out entirely (do not remove vowels).</P
750 >Use only widely-known domain acronyms and abbreviations.
751 Capitalize all letters of an acronym.</P
753 >Use underscore (_) to separate adjacent acronyms and
754 abbreviations. Never terminate a name with an underscore.</P
770 CLASS="PROGRAMLISTING"
771 >#define USE_IMAGE_LIST 1</PRE
791 CLASS="PROGRAMLISTING"
792 >#define USE_IMG_LST 1 or
793 #define _USE_IMAGE_LIST 1 or
794 #define USE_IMAGE_LIST_ 1 or
795 #define use_image_list 1 or
796 #define UseImageList 1</PRE
810 >4.4. Using Space</H2
818 >4.4.1. Put braces on a line by themselves.</H3
828 >The brace needs to be on a line all by itself, not at the
829 end of the statement. Curly braces should line up with the
830 construct that they're associated with. This practice makes it
831 easier to identify the opening and closing braces for a
848 CLASS="PROGRAMLISTING"
865 >if ( this == that ) { ... }</P
869 >if ( this == that ) { ... }</P
877 > In the special case that the if-statement is
878 inside a loop, and it is trivial, i.e. it tests for a
879 condition that is obvious from the purpose of the block,
880 one-liners as above may optically preserve the loop structure
881 and make it easier to read.</P
889 > developer-discretion.</P
895 >Example exception:</I
905 CLASS="PROGRAMLISTING"
906 >while ( more lines are read )
908 /* Please document what is/is not a comment line here */
909 if ( it's a comment ) continue;
911 do_something( line );
924 >4.4.2. ALL control statements should have a
935 >Using braces to make a block will make your code more
936 readable and less prone to error. All control statements should
937 have a block defined.</P
953 CLASS="PROGRAMLISTING"
971 >if ( this == that ) DoSomething(); DoSomethingElse();</P
975 >if ( this == that ) DoSomething();</P
983 > The first example in "Instead of" will execute
984 in a manner other than that which the developer desired (per
985 indentation). Using code braces would have prevented this
986 "feature". The "explanation" and "exception" from the point
987 above also applies.</P
996 >4.4.3. Do not belabor/blow-up boolean
1013 CLASS="PROGRAMLISTING"
1014 >structure->flag = ( condition );</PRE
1027 >if ( condition ) { structure->flag = 1; } else {
1028 structure->flag = 0; }</P
1036 > The former is readable and concise. The later
1037 is wordy and inefficient. Please assume that any developer new
1038 to the project has at least a "good" knowledge of C/C++. (Hope
1039 I do not offend by that last comment ... 8-)</P
1048 >4.4.4. Use white space freely because it is
1059 >Make it readable. The notable exception to using white space
1060 freely is listed in the next guideline.</P
1076 CLASS="PROGRAMLISTING"
1077 >int firstValue = 0;
1079 int anotherValue = 0;
1080 int thisVariable = 0;
1082 if ( thisVariable == thatVariable )
1084 firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )</PRE
1096 >4.4.5. Don't use white space around structure
1107 >- structure pointer operator ( "->" ) - member operator (
1108 "." ) - functions and parentheses</P
1110 >It is a general coding practice to put pointers, references,
1111 and function parentheses next to names. With spaces, the
1112 connection between the object and variable/function name is not
1129 CLASS="PROGRAMLISTING"
1130 >aStruct->aMember;
1132 FunctionName();</PRE
1143 > aStruct -> aMember; aStruct . aMember;
1153 >4.4.6. Make the last brace of a function stand
1170 CLASS="PROGRAMLISTING"
1171 >int function1( ... )
1176 } /* -END- function1 */
1179 int function2( ... )
1181 } /* -END- function2 */</PRE
1194 >int function1( ... ) { ...code... return( retCode ); } int
1195 function2( ... ) { }</P
1203 > Use 1 blank line before the closing brace and 2
1204 lines afterward. This makes the end of function standout to
1205 the most casual viewer. Although function comments help
1206 separate functions, this is still a good coding practice. In
1207 fact, I follow these rules when using blocks in "for", "while",
1208 "do" loops, and long if {} statements too. After all whitespace
1217 > developer-discretion on the number of blank
1218 lines. Enforced is the end of function comments.</P
1227 >4.4.7. Use 3 character indentions</H3
1237 >If some use 8 character TABs and some use 3 character TABs,
1238 the code can look *very* ragged. So use 3 character indentions
1239 only. If you like to use TABs, pass your code through a filter
1240 such as "expand -t3" before checking in your code.</P
1256 CLASS="PROGRAMLISTING"
1257 >static const char * const url_code_map[256] =
1263 int function1( ... )
1267 return( ALWAYS_TRUE );
1271 return( HOW_DID_YOU_GET_HERE );
1274 return( NEVER_GETS_HERE );
1289 >4.5. Initializing</H2
1297 >4.5.1. Initialize all variables</H3
1307 >Do not assume that the variables declared will not be used
1308 until after they have been assigned a value somewhere else in
1309 the code. Remove the chance of accidentally using an unassigned
1326 CLASS="PROGRAMLISTING"
1329 struct *ptr = NULL;</PRE
1340 > It is much easier to debug a SIGSEGV if the
1341 message says you are trying to access memory address 00000000
1342 and not 129FA012; or arrayPtr[20] causes a SIGSEV vs.
1351 > developer-discretion if and only if the
1352 variable is assigned a value "shortly after" declaration.</P
1370 >4.6.1. Name functions that return a boolean as a
1381 >Value should be phrased as a question that would logically
1382 be answered as a true or false statement</P
1398 CLASS="PROGRAMLISTING"
1399 >ShouldWeBlockThis();
1401 IsWebPageBlank();</PRE
1413 >4.6.2. Always specify a return type for a
1424 >The default return for a function is an int. To avoid
1425 ambiguity, create a return for a function when the return has a
1426 purpose, and create a void return type if the function does not
1427 need to return anything.</P
1436 >4.6.3. Minimize function calls when iterating by
1447 >It is easy to write the following code, and a clear argument
1448 can be made that the code is easy to understand:</P
1464 CLASS="PROGRAMLISTING"
1465 >for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
1479 > Unfortunately, this makes a function call for
1480 each and every iteration. This increases the overhead in the
1481 program, because the compiler has to look up the function each
1482 time, call it, and return a value. Depending on what occurs in
1483 the blockListLength() call, it might even be creating and
1484 destroying structures with each iteration, even though in each
1485 case it is comparing "cnt" to the same value, over and over.
1486 Remember too - even a call to blockListLength() is a function
1487 call, with the same overhead.</P
1489 >Instead of using a function call during the iterations,
1490 assign the value to a variable, and evaluate using the
1507 CLASS="PROGRAMLISTING"
1508 >size_t len = blockListLength();
1510 for ( size_t cnt = 0; cnt < len; cnt ++ )
1524 > if the value of blockListLength() *may*
1525 change or could *potentially* change, then you must code the
1526 function call in the for/while loop.</P
1535 >4.6.4. Pass and Return by Const Reference</H3
1545 >This allows a developer to define a const pointer and call
1546 your function. If your function does not have the const
1547 keyword, we may not be able to use your function. Consider
1548 strcmp, if it were defined as: extern int strcmp( char *s1,
1551 >I could then not use it to compare argv's in main: int main(
1552 int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
1555 >Both these pointers are *const*! If the c runtime library
1556 maintainers do it, we should too.</P
1565 >4.6.5. Pass and Return by Value</H3
1575 >Most structures cannot fit onto a normal stack entry (i.e.
1576 they are not 4 bytes or less). Aka, a function declaration
1577 like: int load_aclfile( struct client_state csp )</P
1579 >would not work. So, to be consistent, we should declare all
1580 prototypes with "pass by value": int load_aclfile( struct
1581 client_state *csp )</P
1590 >4.6.6. Names of include files</H3
1600 >Your include statements should contain the file name without
1601 a path. The path should be listed in the Makefile, using -I as
1602 processor directive to search the indicated paths. An exception
1603 to this would be for some proprietary software that utilizes a
1604 partial path to distinguish their header files from system or
1605 other header files.</P
1621 CLASS="PROGRAMLISTING"
1622 >#include <iostream.h> /* This is not a local include */
1623 #include "config.h" /* This IS a local include */</PRE
1643 CLASS="PROGRAMLISTING"
1644 >/* This is not a local include, but requires a path element. */
1645 #include <sys/fileName.h></PRE
1657 > Please! do not add "-I." to the Makefile
1658 without a _very_ good reason. This duplicates the #include
1659 "file.h" behavior.</P
1668 >4.6.7. Provide multiple inclusion
1679 >Prevents compiler and linker errors resulting from
1680 redefinition of items.</P
1682 >Wrap each header file with the following syntax to prevent
1683 multiple inclusions of the file. Of course, replace PROJECT_H
1684 with your file name, with "." Changed to "_", and make it
1701 CLASS="PROGRAMLISTING"
1702 >#ifndef PROJECT_H_INCLUDED
1703 #define PROJECT_H_INCLUDED
1705 #endif /* ndef PROJECT_H_INCLUDED */</PRE
1717 >4.6.8. Use `extern "C"` when appropriate</H3
1727 >If our headers are included from C++, they must declare our
1728 functions as `extern "C"`. This has no cost in C, but increases
1729 the potential re-usability of our code.</P
1745 CLASS="PROGRAMLISTING"
1749 #endif /* def __cplusplus */
1751 ... function definitions here ...
1755 #endif /* def __cplusplus */</PRE
1767 >4.6.9. Where Possible, Use Forward Struct
1768 Declaration Instead of Includes</H3
1778 >Useful in headers that include pointers to other struct's.
1779 Modifications to excess header files may cause needless
1796 CLASS="PROGRAMLISTING"
1797 >/*********************************************************************
1798 * We're avoiding an include statement here!
1799 *********************************************************************/
1801 extern file_list *xyz;</PRE
1812 > If you declare "file_list xyz;" (without the
1813 pointer), then including the proper header file is necessary.
1814 If you only want to prototype a pointer, however, the header
1815 file is unnecessary.</P
1823 > Use with discretion.</P
1833 >4.7. General Coding Practices</H2
1841 >4.7.1. Turn on warnings</H3
1851 >Compiler warnings are meant to help you find bugs. You
1852 should turn on as many as possible. With GCC, the switch is
1853 "-Wall". Try and fix as many warnings as possible.</P
1862 >4.7.2. Provide a default case for all switch
1873 >What you think is guaranteed is never really guaranteed. The
1874 value that you don't think you need to check is the one that
1875 someday will be passed. So, to protect yourself from the
1876 unknown, always have a default step in a switch statement.</P
1892 CLASS="PROGRAMLISTING"
1893 >switch( hash_string( cmd ) )
1895 case hash_actions_file :
1905 ... anomaly code goes here ...
1906 continue; / break; / exit( 1 ); / etc ...
1908 } /* end switch( hash_string( cmd ) ) */</PRE
1919 > If you already have a default condition, you
1920 are obviously exempt from this point. Of note, most of the
1921 WIN32 code calls `DefWindowProc' after the switch statement.
1922 This API call *should* be included in a default statement.</P
1930 > This is not so much a readability issue
1931 as a robust programming issue. The "anomaly code goes here" may
1932 be no more than a print to the STDERR stream (as in
1933 load_config). Or it may really be an ABEND condition.</P
1941 > Programmer discretion is advised.</P
1950 >4.7.3. Try to avoid falling through cases in a
1951 switch statement.</H3
1961 >In general, you will want to have a 'break' statement within
1962 each 'case' of a switch statement. This allows for the code to
1963 be more readable and understandable, and furthermore can
1964 prevent unwanted surprises if someone else later gets creative
1965 and moves the code around.</P
1967 >The language allows you to plan the fall through from one
1968 case statement to another simply by omitting the break
1969 statement within the case statement. This feature does have
1970 benefits, but should only be used in rare cases. In general,
1971 use a break statement for each case statement.</P
1973 >If you choose to allow fall through, you should comment both
1974 the fact of the fall through and reason why you felt it was
1984 >4.7.4. Use 'long' or 'short' Instead of
1995 >On 32-bit platforms, int usually has the range of long. On
1996 16-bit platforms, int has the range of short.</P
2004 > open-to-debate. In the case of most FSF
2005 projects (including X/GNU-Emacs), there are typedefs to int4,
2006 int8, int16, (or equivalence ... I forget the exact typedefs
2007 now). Should we add these to IJB now that we have a "configure"
2017 >4.7.5. Don't mix size_t and other types</H3
2027 >The type of size_t varies across platforms. Do not make
2028 assumptions about whether it is signed or unsigned, or about
2029 how long it is. Do not compare a size_t against another
2030 variable of a different type (or even against a constant)
2031 without casting one of the values. Try to avoid using size_t if
2041 >4.7.6. Declare each variable and struct on its
2052 >It can be tempting to declare a series of variables all on
2069 CLASS="PROGRAMLISTING"
2093 > - there is more room for comments on the
2094 individual variables - easier to add new variables without
2095 messing up the original ones - when searching on a variable to
2096 find its type, there is less clutter to "visually"
2105 > when you want to declare a bunch of loop
2106 variables or other trivial variables; feel free to declare them
2107 on 1 line. You should, although, provide a good comment on
2116 > developer-discretion.</P
2125 >4.7.7. Use malloc/zalloc sparingly</H3
2135 >Create a local struct (on the stack) if the variable will
2136 live and die within the context of one function call.</P
2138 >Only "malloc" a struct (on the heap) if the variable's life
2139 will extend beyond the context of one function call.</P
2155 CLASS="PROGRAMLISTING"
2156 >If a function creates a struct and stores a pointer to it in a
2157 list, then it should definitely be allocated via `malloc'.</PRE
2169 >4.7.8. The Programmer Who Uses 'malloc' is
2170 Responsible for Ensuring 'free'</H3
2180 >If you have to "malloc" an instance, you are responsible for
2181 insuring that the instance is `free'd, even if the deallocation
2182 event falls within some other programmer's code. You are also
2183 responsible for ensuring that deletion is timely (i.e. not too
2184 soon, not too late). This is known as "low-coupling" and is a
2185 "good thing (tm)". You may need to offer a
2186 free/unload/destructor type function to accommodate this.</P
2202 CLASS="PROGRAMLISTING"
2203 >int load_re_filterfile( struct client_state *csp ) { ... }
2204 static void unload_re_filterfile( void *f ) { ... }</PRE
2217 >The developer cannot be expected to provide `free'ing
2218 functions for C run-time library functions ... such as
2227 > developer-discretion. The "main" use of this
2228 standard is for allocating and freeing data structures (complex
2238 >4.7.9. Add loaders to the `file_list' structure
2249 >I have ordered all of the "blocker" file code to be in alpha
2250 order. It is easier to add/read new blockers when you expect a
2259 > It may appear that the alpha order is broken in
2260 places by POPUP tests coming before PCRS tests. But since
2261 POPUPs can also be referred to as KILLPOPUPs, it is clear that
2262 it should come first.</P
2271 >4.7.10. "Uncertain" new code and/or changes to
2272 existing code, use FIXME</H3
2282 >If you have enough confidence in new code or confidence in
2283 your changes, but are not *quite* sure of the repercussions,
2286 >/* FIXME: this code has a logic error on platform XYZ, *
2287 attempting to fix */ #ifdef PLATFORM ...changed code here...
2292 >/* FIXME: I think the original author really meant this...
2293 */ ...changed code here...</P
2297 >/* FIXME: new code that *may* break something else... */
2298 ...new code here...</P
2306 > If you make it clear that this may or may not
2307 be a "good thing (tm)", it will be easier to identify and
2308 include in the project (or conversely exclude from the
2319 >4.8. Addendum: Template for files and function
2326 >Example for file comments:</I
2336 CLASS="PROGRAMLISTING"
2337 >const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $";
2338 /*********************************************************************
2342 * Purpose : (Fill me in with a good description!)
2344 * Copyright : Written by and Copyright (C) 2001 the SourceForge
2345 * Privoxy team. http://www.privoxy.org/
2347 * Based on the Internet Junkbuster originally written
2348 * by and Copyright (C) 1997 Anonymous Coders and
2349 * Junkbusters Corporation. http://www.junkbusters.com
2351 * This program is free software; you can redistribute it
2352 * and/or modify it under the terms of the GNU General
2353 * Public License as published by the Free Software
2354 * Foundation; either version 2 of the License, or (at
2355 * your option) any later version.
2357 * This program is distributed in the hope that it will
2358 * be useful, but WITHOUT ANY WARRANTY; without even the
2359 * implied warranty of MERCHANTABILITY or FITNESS FOR A
2360 * PARTICULAR PURPOSE. See the GNU General Public
2361 * License for more details.
2363 * The GNU General Public License should be included with
2364 * this file. If not, you can view it at
2365 * http://www.gnu.org/copyleft/gpl.html
2366 * or write to the Free Software Foundation, Inc., 59
2367 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2372 *********************************************************************/
2377 ...necessary include files for us to do our work...
2379 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;</PRE
2390 > This declares the rcs variables that should be
2391 added to the "show-proxy-args" page. If this is a brand new
2392 creation by you, you are free to change the "Copyright" section
2393 to represent the rights you wish to maintain.</P
2401 > The formfeed character that is present right
2402 after the comment flower box is handy for (X|GNU)Emacs users to
2403 skip the verbiage and get to the heart of the code (via
2404 `forward-page' and `backward-page'). Please include it if you
2411 >Example for file header comments:</I
2421 CLASS="PROGRAMLISTING"
2422 >#ifndef _FILENAME_H
2424 #define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.7 2006/07/18 14:48:50 david__schmidt Exp $"
2425 /*********************************************************************
2429 * Purpose : (Fill me in with a good description!)
2431 * Copyright : Written by and Copyright (C) 2001 the SourceForge
2432 * Privoxy team. http://www.privoxy.org/
2434 * Based on the Internet Junkbuster originally written
2435 * by and Copyright (C) 1997 Anonymous Coders and
2436 * Junkbusters Corporation. http://www.junkbusters.com
2438 * This program is free software; you can redistribute it
2439 * and/or modify it under the terms of the GNU General
2440 * Public License as published by the Free Software
2441 * Foundation; either version 2 of the License, or (at
2442 * your option) any later version.
2444 * This program is distributed in the hope that it will
2445 * be useful, but WITHOUT ANY WARRANTY; without even the
2446 * implied warranty of MERCHANTABILITY or FITNESS FOR A
2447 * PARTICULAR PURPOSE. See the GNU General Public
2448 * License for more details.
2450 * The GNU General Public License should be included with
2451 * this file. If not, you can view it at
2452 * http://www.gnu.org/copyleft/gpl.html
2453 * or write to the Free Software Foundation, Inc., 59
2454 * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
2459 *********************************************************************/
2462 #include "project.h"
2468 ... function headers here ...
2471 /* Revision control strings from this header and associated .c file */
2472 extern const char FILENAME_rcs[];
2473 extern const char FILENAME_h_rcs[];
2480 #endif /* ndef _FILENAME_H */
2495 >Example for function comments:</I
2505 CLASS="PROGRAMLISTING"
2506 >/*********************************************************************
2508 * Function : FUNCTION_NAME
2510 * Description : (Fill me in with a good description!)
2513 * 1 : param1 = pointer to an important thing
2514 * 2 : x = pointer to something else
2516 * Returns : 0 => Ok, everything else is an error.
2518 *********************************************************************/
2519 int FUNCTION_NAME( void *param1, const char *x )
2535 > If we all follow this practice, we should be
2536 able to parse our code to create a "self-documenting" web
2545 SUMMARY="Footer navigation table"
2556 HREF="documentation.html"
2584 >Documentation Guidelines</TD
2594 >Testing Guidelines</TD
projects / privoxy.git / blob