1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <title>Coding Guidelines</title>
7 <meta name="GENERATOR" content=
8 "Modular DocBook HTML Stylesheet Version 1.79">
9 <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
10 <link rel="PREVIOUS" title="Documentation Guidelines" href=
12 <link rel="NEXT" title="Testing Guidelines" href="testing.html">
13 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
14 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
17 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
18 "#840084" alink="#0000FF">
19 <div class="NAVHEADER">
20 <table summary="Header navigation table" width="100%" border="0"
21 cellpadding="0" cellspacing="0">
23 <th colspan="3" align="center">Privoxy Developer Manual</th>
27 <td width="10%" align="left" valign="bottom"><a href=
28 "documentation.html" accesskey="P">Prev</a></td>
30 <td width="80%" align="center" valign="bottom"></td>
32 <td width="10%" align="right" valign="bottom"><a href="testing.html"
33 accesskey="N">Next</a></td>
36 <hr align="left" width="100%">
40 <h1 class="SECT1"><a name="CODING" id="CODING">4. Coding
44 <h2 class="SECT2"><a name="S1" id="S1">4.1. Introduction</a></h2>
46 <p>This set of standards is designed to make our lives easier. It is
47 developed with the simple goal of helping us keep the "new and improved
48 <span class="APPLICATION">Privoxy</span>" consistent and reliable. Thus
49 making maintenance easier and increasing chances of success of the
52 <p>And that of course comes back to us as individuals. If we can
53 increase our development and product efficiencies then we can solve
54 more of the request for changes/improvements and in general feel good
55 about ourselves. ;-></p>
59 <h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
62 <h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment,
65 <p><span class="emphasis"><i class=
66 "EMPHASIS">Explanation:</i></span></p>
68 <p>Comment as much as possible without commenting the obvious. For
69 example do not comment "variable_a is equal to variable_b". Instead
70 explain why variable_a should be equal to the variable_b. Just
71 because a person can read code does not mean they will understand why
72 or what is being done. A reader may spend a lot more time figuring
73 out what is going on when a simple comment or explanation would have
74 prevented the extra research. Please help your brother IJB'ers
77 <p>The comments will also help justify the intent of the code. If the
78 comment describes something different than what the code is doing
79 then maybe a programming error is occurring.</p>
81 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
83 <table border="0" bgcolor="#E0E0E0" width="100%">
86 <pre class="PROGRAMLISTING">
87 /* if page size greater than 1k ... */
88 if ( page_length() > 1024 )
90 ... "block" the page up ...
93 /* if page size is small, send it in blocks */
94 if ( page_length() > 1024 )
96 ... "block" the page up ...
99 This demonstrates 2 cases of "what not to do". The first is a
100 "syntax comment". The second is a comment that does not fit what
101 is actually being done.
109 <h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for
112 <p><span class="emphasis"><i class=
113 "EMPHASIS">Explanation:</i></span></p>
115 <p>Comments can help or they can clutter. They help when they are
116 differentiated from the code they describe. One line comments do not
117 offer effective separation between the comment and the code. Block
118 identifiers do, by surrounding the code with a clear, definable
121 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
123 <table border="0" bgcolor="#E0E0E0" width="100%">
126 <pre class="PROGRAMLISTING">
127 /*********************************************************************
128 * This will stand out clearly in your code!
129 *********************************************************************/
130 if ( this_variable == that_variable )
132 do_something_very_important();
136 /* unfortunately, this may not */
137 if ( this_variable == that_variable )
139 do_something_very_important();
143 if ( this_variable == that_variable ) /* this may not either */
145 do_something_very_important();
152 <p><span class="emphasis"><i class=
153 "EMPHASIS">Exception:</i></span></p>
155 <p>If you are trying to add a small logic comment and do not wish to
156 "disrupt" the flow of the code, feel free to use a 1 line comment
157 which is NOT on the same line as the code.</p>
161 <h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their
164 <p><span class="emphasis"><i class=
165 "EMPHASIS">Explanation:</i></span></p>
167 <p>It goes back to the question of readability. If the comment is on
168 the same line as the code it will be harder to read than the comment
169 that is on its own line.</p>
171 <p>There are three exceptions to this rule, which should be violated
172 freely and often: during the definition of variables, at the end of
173 closing braces, when used to comment parameters.</p>
175 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
177 <table border="0" bgcolor="#E0E0E0" width="100%">
180 <pre class="PROGRAMLISTING">
181 /*********************************************************************
182 * This will stand out clearly in your code,
183 * But the second example won't.
184 *********************************************************************/
185 if ( this_variable == this_variable )
187 do_something_very_important();
190 if ( this_variable == this_variable ) /*can you see me?*/
192 do_something_very_important(); /*not easily*/
196 /*********************************************************************
197 * But, the encouraged exceptions:
198 *********************************************************************/
199 int urls_read = 0; /* # of urls read + rejected */
200 int urls_rejected = 0; /* # of urls rejected */
204 do_something_very_important();
208 short do_something_very_important(
209 short firstparam, /* represents something */
210 short nextparam /* represents something else */ )
214 } /* -END- do_something_very_important */
222 <h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical
225 <p><span class="emphasis"><i class=
226 "EMPHASIS">Explanation:</i></span></p>
228 <p>Logical steps should be commented to help others follow the intent
229 of the written code and comments will make the code more
232 <p>If you have 25 lines of code without a comment, you should
233 probably go back into it to see where you forgot to put one.</p>
235 <p>Most "for", "while", "do", etc... loops _probably_ need a comment.
236 After all, these are usually major logic containers.</p>
240 <h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions
243 <p><span class="emphasis"><i class=
244 "EMPHASIS">Explanation:</i></span></p>
246 <p>A reader of the code should be able to look at the comments just
247 prior to the beginning of a function and discern the reason for its
248 existence and the consequences of using it. The reader should not
249 have to read through the code to determine if a given function is
250 safe for a desired use. The proper information thoroughly presented
251 at the introduction of a function not only saves time for subsequent
252 maintenance or debugging, it more importantly aids in code reuse by
253 allowing a user to determine the safety and applicability of any
254 function for the problem at hand. As a result of such benefits, all
255 functions should contain the information presented in the addendum
256 section of this document.</p>
260 <h3 class="SECT3"><a name="S8" id="S8">4.2.6. Comment at the end of
261 braces if the content is more than one screen length</a></h3>
263 <p><span class="emphasis"><i class=
264 "EMPHASIS">Explanation:</i></span></p>
266 <p>Each closing brace should be followed on the same line by a
267 comment that describes the origination of the brace if the original
268 brace is off of the screen, or otherwise far away from the closing
269 brace. This will simplify the debugging, maintenance, and readability
272 <p>As a suggestion , use the following flags to make the comment and
273 its brace more readable:</p>
275 <p>use following a closing brace: } /* -END- if() or while () or
278 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
280 <table border="0" bgcolor="#E0E0E0" width="100%">
283 <pre class="PROGRAMLISTING">
286 do_something_very_important();
287 ...some long list of commands...
288 } /* -END- if x is 1 */
294 do_something_very_important();
295 ...some long list of commands...
296 } /* -END- if ( 1 == X ) */
305 <h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
308 <h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable
311 <p><span class="emphasis"><i class=
312 "EMPHASIS">Explanation:</i></span></p>
314 <p>Use all lowercase, and separate words via an underscore ('_'). Do
315 not start an identifier with an underscore. (ANSI C reserves these
316 for use by the compiler and system headers.) Do not use identifiers
317 which are reserved in ANSI C++. (E.g. template, class, true, false,
318 ...). This is in case we ever decide to port Privoxy to C++.</p>
320 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
322 <table border="0" bgcolor="#E0E0E0" width="100%">
325 <pre class="PROGRAMLISTING">
326 int ms_iis5_hack = 0;
332 <p><span class="emphasis"><i class="EMPHASIS">Instead
335 <table border="0" bgcolor="#E0E0E0" width="100%">
338 <pre class="PROGRAMLISTING">
339 int msiis5hack = 0; int msIis5Hack = 0;
347 <h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function
350 <p><span class="emphasis"><i class=
351 "EMPHASIS">Explanation:</i></span></p>
353 <p>Use all lowercase, and separate words via an underscore ('_'). Do
354 not start an identifier with an underscore. (ANSI C reserves these
355 for use by the compiler and system headers.) Do not use identifiers
356 which are reserved in ANSI C++. (E.g. template, class, true, false,
357 ...). This is in case we ever decide to port Privoxy to C++.</p>
359 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
361 <table border="0" bgcolor="#E0E0E0" width="100%">
364 <pre class="PROGRAMLISTING">
365 int load_some_file( struct client_state *csp )
371 <p><span class="emphasis"><i class="EMPHASIS">Instead
374 <table border="0" bgcolor="#E0E0E0" width="100%">
377 <pre class="PROGRAMLISTING">
378 int loadsomefile( struct client_state *csp )
379 int loadSomeFile( struct client_state *csp )
387 <h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file
390 <p><span class="emphasis"><i class=
391 "EMPHASIS">Explanation:</i></span></p>
393 <p>Use a descriptive parameter name in the function prototype in
394 header files. Use the same parameter name in the header file that you
395 use in the c file.</p>
397 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
399 <table border="0" bgcolor="#E0E0E0" width="100%">
402 <pre class="PROGRAMLISTING">
403 (.h) extern int load_aclfile( struct client_state *csp );
404 (.c) int load_aclfile( struct client_state *csp )
410 <p><span class="emphasis"><i class="EMPHASIS">Instead
413 <table border="0" bgcolor="#E0E0E0" width="100%">
416 <pre class="PROGRAMLISTING">
417 (.h) extern int load_aclfile( struct client_state * ); or
418 (.h) extern int load_aclfile();
419 (.c) int load_aclfile( struct client_state *csp )
427 <h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and
430 <p><span class="emphasis"><i class=
431 "EMPHASIS">Explanation:</i></span></p>
433 <p>Use all capital letters, with underscores between words. Do not
434 start an identifier with an underscore. (ANSI C reserves these for
435 use by the compiler and system headers.)</p>
437 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
439 <table border="0" bgcolor="#E0E0E0" width="100%">
442 <pre class="PROGRAMLISTING">
443 (enumeration) : enum Boolean { FALSE, TRUE };
444 (#define) : #define DEFAULT_SIZE 100;
450 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> We
451 have a standard naming scheme for #defines that toggle a feature in
452 the preprocessor: FEATURE_>, where > is a short (preferably 1
453 or 2 word) description.</p>
455 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
457 <table border="0" bgcolor="#E0E0E0" width="100%">
460 <pre class="PROGRAMLISTING">
461 #define FEATURE_FORCE 1
464 #define FORCE_PREFIX blah
465 #endif /* def FEATURE_FORCE */
473 <h3 class="SECT3"><a name="S14" id="S14">4.3.5. Constants</a></h3>
475 <p><span class="emphasis"><i class=
476 "EMPHASIS">Explanation:</i></span></p>
478 <p>Spell common words out entirely (do not remove vowels).</p>
480 <p>Use only widely-known domain acronyms and abbreviations.
481 Capitalize all letters of an acronym.</p>
483 <p>Use underscore (_) to separate adjacent acronyms and
484 abbreviations. Never terminate a name with an underscore.</p>
486 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
488 <table border="0" bgcolor="#E0E0E0" width="100%">
491 <pre class="PROGRAMLISTING">
492 #define USE_IMAGE_LIST 1
498 <p><span class="emphasis"><i class="EMPHASIS">Instead
501 <table border="0" bgcolor="#E0E0E0" width="100%">
504 <pre class="PROGRAMLISTING">
505 #define USE_IMG_LST 1 or
506 #define _USE_IMAGE_LIST 1 or
507 #define USE_IMAGE_LIST_ 1 or
508 #define use_image_list 1 or
509 #define UseImageList 1
518 <h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
521 <h3 class="SECT3"><a name="S16" id="S16">4.4.1. Put braces on a line
522 by themselves.</a></h3>
524 <p><span class="emphasis"><i class=
525 "EMPHASIS">Explanation:</i></span></p>
527 <p>The brace needs to be on a line all by itself, not at the end of
528 the statement. Curly braces should line up with the construct that
529 they're associated with. This practice makes it easier to identify
530 the opening and closing braces for a block.</p>
532 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
534 <table border="0" bgcolor="#E0E0E0" width="100%">
537 <pre class="PROGRAMLISTING">
547 <p><span class="emphasis"><i class="EMPHASIS">Instead
550 <p>if ( this == that ) { ... }</p>
554 <p>if ( this == that ) { ... }</p>
556 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> In the
557 special case that the if-statement is inside a loop, and it is
558 trivial, i.e. it tests for a condition that is obvious from the
559 purpose of the block, one-liners as above may optically preserve the
560 loop structure and make it easier to read.</p>
562 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
563 developer-discretion.</p>
565 <p><span class="emphasis"><i class="EMPHASIS">Example
566 exception:</i></span></p>
568 <table border="0" bgcolor="#E0E0E0" width="100%">
571 <pre class="PROGRAMLISTING">
572 while ( more lines are read )
574 /* Please document what is/is not a comment line here */
575 if ( it's a comment ) continue;
577 do_something( line );
586 <h3 class="SECT3"><a name="S17" id="S17">4.4.2. ALL control
587 statements should have a block</a></h3>
589 <p><span class="emphasis"><i class=
590 "EMPHASIS">Explanation:</i></span></p>
592 <p>Using braces to make a block will make your code more readable and
593 less prone to error. All control statements should have a block
596 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
598 <table border="0" bgcolor="#E0E0E0" width="100%">
601 <pre class="PROGRAMLISTING">
612 <p><span class="emphasis"><i class="EMPHASIS">Instead
615 <p>if ( this == that ) do_something(); do_something_else();</p>
619 <p>if ( this == that ) do_something();</p>
621 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
622 first example in "Instead of" will execute in a manner other than
623 that which the developer desired (per indentation). Using code braces
624 would have prevented this "feature". The "explanation" and
625 "exception" from the point above also applies.</p>
629 <h3 class="SECT3"><a name="S18" id="S18">4.4.3. Do not
630 belabor/blow-up boolean expressions</a></h3>
632 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
634 <table border="0" bgcolor="#E0E0E0" width="100%">
637 <pre class="PROGRAMLISTING">
638 structure->flag = ( condition );
644 <p><span class="emphasis"><i class="EMPHASIS">Instead
647 <p>if ( condition ) { structure->flag = 1; } else {
648 structure->flag = 0; }</p>
650 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
651 former is readable and concise. The later is wordy and inefficient.
652 Please assume that any developer new to the project has at least a
653 "good" knowledge of C/C++. (Hope I do not offend by that last comment
658 <h3 class="SECT3"><a name="S19" id="S19">4.4.4. Use white space
659 freely because it is free</a></h3>
661 <p><span class="emphasis"><i class=
662 "EMPHASIS">Explanation:</i></span></p>
664 <p>Make it readable. The notable exception to using white space
665 freely is listed in the next guideline.</p>
667 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
669 <table border="0" bgcolor="#E0E0E0" width="100%">
672 <pre class="PROGRAMLISTING">
675 int another_value = 0;
676 int this_variable = 0;
678 if ( this_variable == this_variable )
680 first_value = old_value + ( ( some_value - another_value ) - whatever )
688 <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
689 around structure operators</a></h3>
691 <p><span class="emphasis"><i class=
692 "EMPHASIS">Explanation:</i></span></p>
694 <p>- structure pointer operator ( "->" ) - member operator ( "." )
695 - functions and parentheses</p>
697 <p>It is a general coding practice to put pointers, references, and
698 function parentheses next to names. With spaces, the connection
699 between the object and variable/function name is not as clear.</p>
701 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
703 <table border="0" bgcolor="#E0E0E0" width="100%">
706 <pre class="PROGRAMLISTING">
707 a_struct->a_member;
715 <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
716 a_struct -> a_member; a_struct . a_member; function_name ();</p>
720 <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
721 of a function stand out</a></h3>
723 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
725 <table border="0" bgcolor="#E0E0E0" width="100%">
728 <pre class="PROGRAMLISTING">
734 } /* -END- function1 */
739 } /* -END- function2 */
745 <p><span class="emphasis"><i class="EMPHASIS">Instead
748 <p>int function1( ... ) { ...code... return( ret_code ); } int
749 function2( ... ) { }</p>
751 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> Use 1
752 blank line before the closing brace and 2 lines afterward. This makes
753 the end of function standout to the most casual viewer. Although
754 function comments help separate functions, this is still a good
755 coding practice. In fact, I follow these rules when using blocks in
756 "for", "while", "do" loops, and long if {} statements too. After all
757 whitespace is free!</p>
759 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
760 developer-discretion on the number of blank lines. Enforced is the
761 end of function comments.</p>
765 <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
768 <p><span class="emphasis"><i class=
769 "EMPHASIS">Explanation:</i></span></p>
771 <p>If some use 8 character TABs and some use 3 character TABs, the
772 code can look *very* ragged. So use 3 character indentions only. If
773 you like to use TABs, pass your code through a filter such as "expand
774 -t3" before checking in your code.</p>
776 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
778 <table border="0" bgcolor="#E0E0E0" width="100%">
781 <pre class="PROGRAMLISTING">
782 static const char * const url_code_map[256] =
792 return( ALWAYS_TRUE );
796 return( HOW_DID_YOU_GET_HERE );
799 return( NEVER_GETS_HERE );
810 <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
813 <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
816 <p><span class="emphasis"><i class=
817 "EMPHASIS">Explanation:</i></span></p>
819 <p>Do not assume that the variables declared will not be used until
820 after they have been assigned a value somewhere else in the code.
821 Remove the chance of accidentally using an unassigned variable.</p>
823 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
825 <table border="0" bgcolor="#E0E0E0" width="100%">
828 <pre class="PROGRAMLISTING">
837 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It is
838 much easier to debug a SIGSEGV if the message says you are trying to
839 access memory address 00000000 and not 129FA012; or array_ptr[20]
840 causes a SIGSEV vs. array_ptr[0].</p>
842 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
843 developer-discretion if and only if the variable is assigned a value
844 "shortly after" declaration.</p>
849 <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
852 <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
853 return a boolean as a question.</a></h3>
855 <p><span class="emphasis"><i class=
856 "EMPHASIS">Explanation:</i></span></p>
858 <p>Value should be phrased as a question that would logically be
859 answered as a true or false statement</p>
861 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
863 <table border="0" bgcolor="#E0E0E0" width="100%">
866 <pre class="PROGRAMLISTING">
867 should_we_block_this();
877 <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
878 return type for a function.</a></h3>
880 <p><span class="emphasis"><i class=
881 "EMPHASIS">Explanation:</i></span></p>
883 <p>The default return for a function is an int. To avoid ambiguity,
884 create a return for a function when the return has a purpose, and
885 create a void return type if the function does not need to return
890 <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
891 calls when iterating by using variables</a></h3>
893 <p><span class="emphasis"><i class=
894 "EMPHASIS">Explanation:</i></span></p>
896 <p>It is easy to write the following code, and a clear argument can
897 be made that the code is easy to understand:</p>
899 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
901 <table border="0" bgcolor="#E0E0E0" width="100%">
904 <pre class="PROGRAMLISTING">
905 for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
914 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
915 Unfortunately, this makes a function call for each and every
916 iteration. This increases the overhead in the program, because the
917 compiler has to look up the function each time, call it, and return a
918 value. Depending on what occurs in the block_list_length() call, it
919 might even be creating and destroying structures with each iteration,
920 even though in each case it is comparing "cnt" to the same value,
921 over and over. Remember too - even a call to block_list_length() is a
922 function call, with the same overhead.</p>
924 <p>Instead of using a function call during the iterations, assign the
925 value to a variable, and evaluate using the variable.</p>
927 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
929 <table border="0" bgcolor="#E0E0E0" width="100%">
932 <pre class="PROGRAMLISTING">
933 size_t len = block_list_length();
935 for ( size_t cnt = 0; cnt < len; cnt++ )
944 <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
945 if the value of block_list_length() *may* change or could
946 *potentially* change, then you must code the function call in the
951 <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
952 Const Reference</a></h3>
954 <p><span class="emphasis"><i class=
955 "EMPHASIS">Explanation:</i></span></p>
957 <p>This allows a developer to define a const pointer and call your
958 function. If your function does not have the const keyword, we may
959 not be able to use your function. Consider strcmp, if it were defined
960 as: extern int strcmp( char *s1, char *s2 );</p>
962 <p>I could then not use it to compare argv's in main: int main( int
963 argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); }</p>
965 <p>Both these pointers are *const*! If the c runtime library
966 maintainers do it, we should too.</p>
970 <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
973 <p><span class="emphasis"><i class=
974 "EMPHASIS">Explanation:</i></span></p>
976 <p>Most structures cannot fit onto a normal stack entry (i.e. they
977 are not 4 bytes or less). Aka, a function declaration like: int
978 load_aclfile( struct client_state csp )</p>
980 <p>would not work. So, to be consistent, we should declare all
981 prototypes with "pass by value": int load_aclfile( struct
982 client_state *csp )</p>
986 <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
989 <p><span class="emphasis"><i class=
990 "EMPHASIS">Explanation:</i></span></p>
992 <p>Your include statements should contain the file name without a
993 path. The path should be listed in the Makefile, using -I as
994 processor directive to search the indicated paths. An exception to
995 this would be for some proprietary software that utilizes a partial
996 path to distinguish their header files from system or other header
999 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1001 <table border="0" bgcolor="#E0E0E0" width="100%">
1004 <pre class="PROGRAMLISTING">
1005 #include <iostream.h> /* This is not a local include */
1006 #include "config.h" /* This IS a local include */
1012 <p><span class="emphasis"><i class=
1013 "EMPHASIS">Exception:</i></span></p>
1015 <table border="0" bgcolor="#E0E0E0" width="100%">
1018 <pre class="PROGRAMLISTING">
1019 /* This is not a local include, but requires a path element. */
1020 #include <sys/fileName.h>
1026 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
1027 Please! do not add "-I." to the Makefile without a _very_ good
1028 reason. This duplicates the #include "file.h" behavior.</p>
1032 <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
1033 inclusion protection</a></h3>
1035 <p><span class="emphasis"><i class=
1036 "EMPHASIS">Explanation:</i></span></p>
1038 <p>Prevents compiler and linker errors resulting from redefinition of
1041 <p>Wrap each header file with the following syntax to prevent
1042 multiple inclusions of the file. Of course, replace PROJECT_H with
1043 your file name, with "." Changed to "_", and make it uppercase.</p>
1045 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1047 <table border="0" bgcolor="#E0E0E0" width="100%">
1050 <pre class="PROGRAMLISTING">
1051 #ifndef PROJECT_H_INCLUDED
1052 #define PROJECT_H_INCLUDED
1054 #endif /* ndef PROJECT_H_INCLUDED */
1062 <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
1063 appropriate</a></h3>
1065 <p><span class="emphasis"><i class=
1066 "EMPHASIS">Explanation:</i></span></p>
1068 <p>If our headers are included from C++, they must declare our
1069 functions as `extern "C"`. This has no cost in C, but increases the
1070 potential re-usability of our code.</p>
1072 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1074 <table border="0" bgcolor="#E0E0E0" width="100%">
1077 <pre class="PROGRAMLISTING">
1081 #endif /* def __cplusplus */
1083 ... function definitions here ...
1087 #endif /* def __cplusplus */
1095 <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
1096 Forward Struct Declaration Instead of Includes</a></h3>
1098 <p><span class="emphasis"><i class=
1099 "EMPHASIS">Explanation:</i></span></p>
1101 <p>Useful in headers that include pointers to other struct's.
1102 Modifications to excess header files may cause needless compiles.</p>
1104 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1106 <table border="0" bgcolor="#E0E0E0" width="100%">
1109 <pre class="PROGRAMLISTING">
1110 /*********************************************************************
1111 * We're avoiding an include statement here!
1112 *********************************************************************/
1114 extern file_list *xyz;
1120 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1121 declare "file_list xyz;" (without the pointer), then including the
1122 proper header file is necessary. If you only want to prototype a
1123 pointer, however, the header file is unnecessary.</p>
1125 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> Use
1126 with discretion.</p>
1131 <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
1135 <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
1138 <p><span class="emphasis"><i class=
1139 "EMPHASIS">Explanation</i></span></p>
1141 <p>Compiler warnings are meant to help you find bugs. You should turn
1142 on as many as possible. With GCC, the switch is "-Wall". Try and fix
1143 as many warnings as possible.</p>
1147 <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
1148 case for all switch statements</a></h3>
1150 <p><span class="emphasis"><i class=
1151 "EMPHASIS">Explanation:</i></span></p>
1153 <p>What you think is guaranteed is never really guaranteed. The value
1154 that you don't think you need to check is the one that someday will
1155 be passed. So, to protect yourself from the unknown, always have a
1156 default step in a switch statement.</p>
1158 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1160 <table border="0" bgcolor="#E0E0E0" width="100%">
1163 <pre class="PROGRAMLISTING">
1164 switch( hash_string( cmd ) )
1166 case hash_actions_file :
1176 ... anomaly code goes here ...
1177 continue; / break; / exit( 1 ); / etc ...
1179 } /* end switch( hash_string( cmd ) ) */
1185 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1186 already have a default condition, you are obviously exempt from this
1187 point. Of note, most of the WIN32 code calls `DefWindowProc' after
1188 the switch statement. This API call *should* be included in a default
1191 <p><span class="emphasis"><i class="EMPHASIS">Another
1192 Note:</i></span> This is not so much a readability issue as a robust
1193 programming issue. The "anomaly code goes here" may be no more than a
1194 print to the STDERR stream (as in load_config). Or it may really be
1195 an abort condition.</p>
1197 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1198 Programmer discretion is advised.</p>
1202 <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
1203 through cases in a switch statement.</a></h3>
1205 <p><span class="emphasis"><i class=
1206 "EMPHASIS">Explanation:</i></span></p>
1208 <p>In general, you will want to have a 'break' statement within each
1209 'case' of a switch statement. This allows for the code to be more
1210 readable and understandable, and furthermore can prevent unwanted
1211 surprises if someone else later gets creative and moves the code
1214 <p>The language allows you to plan the fall through from one case
1215 statement to another simply by omitting the break statement within
1216 the case statement. This feature does have benefits, but should only
1217 be used in rare cases. In general, use a break statement for each
1220 <p>If you choose to allow fall through, you should comment both the
1221 fact of the fall through and reason why you felt it was
1226 <h3 class="SECT3"><a name="S39" id="S39">4.7.4. Use 'long' or 'short'
1227 Instead of 'int'</a></h3>
1229 <p><span class="emphasis"><i class=
1230 "EMPHASIS">Explanation:</i></span></p>
1232 <p>On 32-bit platforms, int usually has the range of long. On 16-bit
1233 platforms, int has the range of short.</p>
1235 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1236 open-to-debate. In the case of most FSF projects (including
1237 X/GNU-Emacs), there are typedefs to int4, int8, int16, (or
1238 equivalence ... I forget the exact typedefs now). Should we add these
1239 to IJB now that we have a "configure" script?</p>
1243 <h3 class="SECT3"><a name="S40" id="S40">4.7.5. Don't mix size_t and
1244 other types</a></h3>
1246 <p><span class="emphasis"><i class=
1247 "EMPHASIS">Explanation:</i></span></p>
1249 <p>The type of size_t varies across platforms. Do not make
1250 assumptions about whether it is signed or unsigned, or about how long
1251 it is. Do not compare a size_t against another variable of a
1252 different type (or even against a constant) without casting one of
1257 <h3 class="SECT3"><a name="S41" id="S41">4.7.6. Declare each variable
1258 and struct on its own line.</a></h3>
1260 <p><span class="emphasis"><i class=
1261 "EMPHASIS">Explanation:</i></span></p>
1263 <p>It can be tempting to declare a series of variables all on one
1266 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1268 <table border="0" bgcolor="#E0E0E0" width="100%">
1271 <pre class="PROGRAMLISTING">
1280 <p><span class="emphasis"><i class="EMPHASIS">Instead
1283 <p>long a, b, c;</p>
1285 <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span>
1286 - there is more room for comments on the individual variables -
1287 easier to add new variables without messing up the original ones -
1288 when searching on a variable to find its type, there is less clutter
1289 to "visually" eliminate</p>
1291 <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
1292 when you want to declare a bunch of loop variables or other trivial
1293 variables; feel free to declare them on one line. You should,
1294 although, provide a good comment on their functions.</p>
1296 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1297 developer-discretion.</p>
1301 <h3 class="SECT3"><a name="S42" id="S42">4.7.7. Use malloc/zalloc
1304 <p><span class="emphasis"><i class=
1305 "EMPHASIS">Explanation:</i></span></p>
1307 <p>Create a local struct (on the stack) if the variable will live and
1308 die within the context of one function call.</p>
1310 <p>Only "malloc" a struct (on the heap) if the variable's life will
1311 extend beyond the context of one function call.</p>
1313 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1315 <table border="0" bgcolor="#E0E0E0" width="100%">
1318 <pre class="PROGRAMLISTING">
1319 If a function creates a struct and stores a pointer to it in a
1320 list, then it should definitely be allocated via `malloc'.
1328 <h3 class="SECT3"><a name="S43" id="S43">4.7.8. The Programmer Who
1329 Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
1331 <p><span class="emphasis"><i class=
1332 "EMPHASIS">Explanation:</i></span></p>
1334 <p>If you have to "malloc" an instance, you are responsible for
1335 insuring that the instance is `free'd, even if the deallocation event
1336 falls within some other programmer's code. You are also responsible
1337 for ensuring that deletion is timely (i.e. not too soon, not too
1338 late). This is known as "low-coupling" and is a "good thing (tm)".
1339 You may need to offer a free/unload/destructor type function to
1340 accommodate this.</p>
1342 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1344 <table border="0" bgcolor="#E0E0E0" width="100%">
1347 <pre class="PROGRAMLISTING">
1348 int load_re_filterfile( struct client_state *csp ) { ... }
1349 static void unload_re_filterfile( void *f ) { ... }
1355 <p><span class="emphasis"><i class=
1356 "EMPHASIS">Exceptions:</i></span></p>
1358 <p>The developer cannot be expected to provide `free'ing functions
1359 for C run-time library functions ... such as `strdup'.</p>
1361 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1362 developer-discretion. The "main" use of this standard is for
1363 allocating and freeing data structures (complex or nested).</p>
1367 <h3 class="SECT3"><a name="S44" id="S44">4.7.9. Add loaders to the
1368 `file_list' structure and in order</a></h3>
1370 <p><span class="emphasis"><i class=
1371 "EMPHASIS">Explanation:</i></span></p>
1373 <p>I have ordered all of the "blocker" file code to be in alpha
1374 order. It is easier to add/read new blockers when you expect a
1377 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It may
1378 appear that the alpha order is broken in places by POPUP tests coming
1379 before PCRS tests. But since POPUPs can also be referred to as
1380 KILLPOPUPs, it is clear that it should come first.</p>
1384 <h3 class="SECT3"><a name="S45" id="S45">4.7.10. "Uncertain" new code
1385 and/or changes to existing code, use FIXME or XXX</a></h3>
1387 <p><span class="emphasis"><i class=
1388 "EMPHASIS">Explanation:</i></span></p>
1390 <p>If you have enough confidence in new code or confidence in your
1391 changes, but are not *quite* sure of the repercussions, add this:</p>
1393 <p>/* FIXME: this code has a logic error on platform XYZ, *
1394 attempting to fix */ #ifdef PLATFORM ...changed code here...
1399 <p>/* FIXME: I think the original author really meant this... */
1400 ...changed code here...</p>
1404 <p>/* FIXME: new code that *may* break something else... */ ...new
1407 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1408 make it clear that this may or may not be a "good thing (tm)", it
1409 will be easier to identify and include in the project (or conversely
1410 exclude from the project).</p>
1415 <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
1416 files and function comment blocks:</a></h2>
1418 <p><span class="emphasis"><i class="EMPHASIS">Example for file
1419 comments:</i></span></p>
1421 <table border="0" bgcolor="#E0E0E0" width="100%">
1424 <pre class="PROGRAMLISTING">
1425 const char FILENAME_rcs[] = "$Id$";
1426 /*********************************************************************
1430 * Purpose : (Fill me in with a good description!)
1432 * Copyright : Written by and Copyright (C) 2001-2009
1433 * the Privoxy team. http://www.privoxy.org/
1435 * This program is free software; you can redistribute it
1436 * and/or modify it under the terms of the GNU General
1437 * Public License as published by the Free Software
1438 * Foundation; either version 2 of the License, or (at
1439 * your option) any later version.
1441 * This program is distributed in the hope that it will
1442 * be useful, but WITHOUT ANY WARRANTY; without even the
1443 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1444 * PARTICULAR PURPOSE. See the GNU General Public
1445 * License for more details.
1447 * The GNU General Public License should be included with
1448 * this file. If not, you can view it at
1449 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1450 * or write to the Free Software Foundation, Inc.,
1451 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1454 *********************************************************************/
1459 ...necessary include files for us to do our work...
1461 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1467 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> This
1468 declares the rcs variables that should be added to the
1469 "show-proxy-args" page. If this is a brand new creation by you, you are
1470 free to change the "Copyright" section to represent the rights you wish
1473 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
1474 formfeed character that is present right after the comment flower box
1475 is handy for (X|GNU)Emacs users to skip the verbiage and get to the
1476 heart of the code (via `forward-page' and `backward-page'). Please
1477 include it if you can.</p>
1479 <p><span class="emphasis"><i class="EMPHASIS">Example for file header
1480 comments:</i></span></p>
1482 <table border="0" bgcolor="#E0E0E0" width="100%">
1485 <pre class="PROGRAMLISTING">
1488 #define FILENAME_H_VERSION "$Id$"
1489 /*********************************************************************
1493 * Purpose : (Fill me in with a good description!)
1495 * Copyright : Written by and Copyright (C) 2001-2009
1496 * the Privoxy team. http://www.privoxy.org/
1498 * This program is free software; you can redistribute it
1499 * and/or modify it under the terms of the GNU General
1500 * Public License as published by the Free Software
1501 * Foundation; either version 2 of the License, or (at
1502 * your option) any later version.
1504 * This program is distributed in the hope that it will
1505 * be useful, but WITHOUT ANY WARRANTY; without even the
1506 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1507 * PARTICULAR PURPOSE. See the GNU General Public
1508 * License for more details.
1510 * The GNU General Public License should be included with
1511 * this file. If not, you can view it at
1512 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1513 * or write to the Free Software Foundation, Inc.,
1514 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1517 *********************************************************************/
1520 #include "project.h"
1526 ... function headers here ...
1529 /* Revision control strings from this header and associated .c file */
1530 extern const char FILENAME_rcs[];
1531 extern const char FILENAME_h_rcs[];
1538 #endif /* ndef _FILENAME_H */
1550 <p><span class="emphasis"><i class="EMPHASIS">Example for function
1551 comments:</i></span></p>
1553 <table border="0" bgcolor="#E0E0E0" width="100%">
1556 <pre class="PROGRAMLISTING">
1557 /*********************************************************************
1559 * Function : FUNCTION_NAME
1561 * Description : (Fill me in with a good description!)
1564 * 1 : param1 = pointer to an important thing
1565 * 2 : x = pointer to something else
1567 * Returns : 0 => Ok, everything else is an error.
1569 *********************************************************************/
1570 int FUNCTION_NAME( void *param1, const char *x )
1581 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If we
1582 all follow this practice, we should be able to parse our code to create
1583 a "self-documenting" web page.</p>
1587 <div class="NAVFOOTER">
1588 <hr align="left" width="100%">
1590 <table summary="Footer navigation table" width="100%" border="0"
1591 cellpadding="0" cellspacing="0">
1593 <td width="33%" align="left" valign="top"><a href=
1594 "documentation.html" accesskey="P">Prev</a></td>
1596 <td width="34%" align="center" valign="top"><a href="index.html"
1597 accesskey="H">Home</a></td>
1599 <td width="33%" align="right" valign="top"><a href="testing.html"
1600 accesskey="N">Next</a></td>
1604 <td width="33%" align="left" valign="top">Documentation
1607 <td width="34%" align="center" valign="top"> </td>
1609 <td width="33%" align="right" valign="top">Testing Guidelines</td>