1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
6 <meta name="generator" content=
7 "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
9 <title>Coding Guidelines</title>
10 <meta name="GENERATOR" content=
11 "Modular DocBook HTML Stylesheet Version 1.79">
12 <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
13 <link rel="PREVIOUS" title="Documentation Guidelines" href=
15 <link rel="NEXT" title="Testing Guidelines" href="testing.html">
16 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
17 <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
18 <style type="text/css">
20 background-color: #EEEEEE;
23 :link { color: #0000FF }
24 :visited { color: #840084 }
25 :active { color: #0000FF }
26 table.c3 {background-color: #E0E0E0}
27 span.c2 {font-style: italic}
28 hr.c1 {text-align: left}
33 <div class="NAVHEADER">
34 <table summary="Header navigation table" width="100%" border="0"
35 cellpadding="0" cellspacing="0">
37 <th colspan="3" align="center">Privoxy Developer Manual</th>
41 <td width="10%" align="left" valign="bottom"><a href=
42 "documentation.html" accesskey="P">Prev</a></td>
44 <td width="80%" align="center" valign="bottom"></td>
46 <td width="10%" align="right" valign="bottom"><a href="testing.html"
47 accesskey="N">Next</a></td>
50 <hr class="c1" width="100%">
54 <h1 class="SECT1"><a name="CODING" id="CODING">4. Coding
58 <h2 class="SECT2"><a name="S1" id="S1">4.1. Introduction</a></h2>
60 <p>This set of standards is designed to make our lives easier. It is
61 developed with the simple goal of helping us keep the "new and improved
62 <span class="APPLICATION">Privoxy</span>" consistent and reliable. Thus
63 making maintenance easier and increasing chances of success of the
66 <p>And that of course comes back to us as individuals. If we can
67 increase our development and product efficiencies then we can solve
68 more of the request for changes/improvements and in general feel good
69 about ourselves. ;-></p>
73 <h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
76 <h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment,
79 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
81 <p>Comment as much as possible without commenting the obvious. For
82 example do not comment "variable_a is equal to variable_b". Instead
83 explain why variable_a should be equal to the variable_b. Just
84 because a person can read code does not mean they will understand why
85 or what is being done. A reader may spend a lot more time figuring
86 out what is going on when a simple comment or explanation would have
87 prevented the extra research. Please help your brother IJB'ers
90 <p>The comments will also help justify the intent of the code. If the
91 comment describes something different than what the code is doing
92 then maybe a programming error is occurring.</p>
94 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
96 <table class="c3" border="0" width="100%">
99 <pre class="PROGRAMLISTING">
100 /* if page size greater than 1k ... */
101 if ( page_length() > 1024 )
103 ... "block" the page up ...
106 /* if page size is small, send it in blocks */
107 if ( page_length() > 1024 )
109 ... "block" the page up ...
112 This demonstrates 2 cases of "what not to do". The first is a
113 "syntax comment". The second is a comment that does not fit what
114 is actually being done.
122 <h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for
125 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
127 <p>Comments can help or they can clutter. They help when they are
128 differentiated from the code they describe. One line comments do not
129 offer effective separation between the comment and the code. Block
130 identifiers do, by surrounding the code with a clear, definable
133 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
135 <table class="c3" border="0" width="100%">
138 <pre class="PROGRAMLISTING">
139 /*********************************************************************
140 * This will stand out clearly in your code!
141 *********************************************************************/
142 if ( this_variable == that_variable )
144 do_something_very_important();
148 /* unfortunately, this may not */
149 if ( this_variable == that_variable )
151 do_something_very_important();
155 if ( this_variable == that_variable ) /* this may not either */
157 do_something_very_important();
164 <p><span class="emphasis EMPHASIS c2">Exception:</span></p>
166 <p>If you are trying to add a small logic comment and do not wish to
167 "disrupt" the flow of the code, feel free to use a 1 line comment
168 which is NOT on the same line as the code.</p>
172 <h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their
175 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
177 <p>It goes back to the question of readability. If the comment is on
178 the same line as the code it will be harder to read than the comment
179 that is on its own line.</p>
181 <p>There are three exceptions to this rule, which should be violated
182 freely and often: during the definition of variables, at the end of
183 closing braces, when used to comment parameters.</p>
185 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
187 <table class="c3" border="0" width="100%">
190 <pre class="PROGRAMLISTING">
191 /*********************************************************************
192 * This will stand out clearly in your code,
193 * But the second example won't.
194 *********************************************************************/
195 if ( this_variable == this_variable )
197 do_something_very_important();
200 if ( this_variable == this_variable ) /*can you see me?*/
202 do_something_very_important(); /*not easily*/
206 /*********************************************************************
207 * But, the encouraged exceptions:
208 *********************************************************************/
209 int urls_read = 0; /* # of urls read + rejected */
210 int urls_rejected = 0; /* # of urls rejected */
214 do_something_very_important();
218 short do_something_very_important(
219 short firstparam, /* represents something */
220 short nextparam /* represents something else */ )
224 } /* -END- do_something_very_important */
232 <h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical
235 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
237 <p>Logical steps should be commented to help others follow the intent
238 of the written code and comments will make the code more
241 <p>If you have 25 lines of code without a comment, you should
242 probably go back into it to see where you forgot to put one.</p>
244 <p>Most "for", "while", "do", etc... loops _probably_ need a comment.
245 After all, these are usually major logic containers.</p>
249 <h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions
252 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
254 <p>A reader of the code should be able to look at the comments just
255 prior to the beginning of a function and discern the reason for its
256 existence and the consequences of using it. The reader should not
257 have to read through the code to determine if a given function is
258 safe for a desired use. The proper information thoroughly presented
259 at the introduction of a function not only saves time for subsequent
260 maintenance or debugging, it more importantly aids in code reuse by
261 allowing a user to determine the safety and applicability of any
262 function for the problem at hand. As a result of such benefits, all
263 functions should contain the information presented in the addendum
264 section of this document.</p>
268 <h3 class="SECT3"><a name="S8" id="S8">4.2.6. Comment at the end of
269 braces if the content is more than one screen length</a></h3>
271 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
273 <p>Each closing brace should be followed on the same line by a
274 comment that describes the origination of the brace if the original
275 brace is off of the screen, or otherwise far away from the closing
276 brace. This will simplify the debugging, maintenance, and readability
279 <p>As a suggestion , use the following flags to make the comment and
280 its brace more readable:</p>
282 <p>use following a closing brace: } /* -END- if() or while () or
285 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
287 <table class="c3" border="0" width="100%">
290 <pre class="PROGRAMLISTING">
293 do_something_very_important();
294 ...some long list of commands...
295 } /* -END- if x is 1 */
301 do_something_very_important();
302 ...some long list of commands...
303 } /* -END- if ( 1 == X ) */
312 <h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
315 <h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable
318 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
320 <p>Use all lowercase, and separate words via an underscore ('_'). Do
321 not start an identifier with an underscore. (ANSI C reserves these
322 for use by the compiler and system headers.) Do not use identifiers
323 which are reserved in ANSI C++. (E.g. template, class, true, false,
324 ...). This is in case we ever decide to port Privoxy to C++.</p>
326 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
328 <table class="c3" border="0" width="100%">
331 <pre class="PROGRAMLISTING">
332 int ms_iis5_hack = 0;
338 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
340 <table class="c3" border="0" width="100%">
343 <pre class="PROGRAMLISTING">
344 int msiis5hack = 0; int msIis5Hack = 0;
352 <h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function
355 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
357 <p>Use all lowercase, and separate words via an underscore ('_'). Do
358 not start an identifier with an underscore. (ANSI C reserves these
359 for use by the compiler and system headers.) Do not use identifiers
360 which are reserved in ANSI C++. (E.g. template, class, true, false,
361 ...). This is in case we ever decide to port Privoxy to C++.</p>
363 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
365 <table class="c3" border="0" width="100%">
368 <pre class="PROGRAMLISTING">
369 int load_some_file( struct client_state *csp )
375 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
377 <table class="c3" border="0" width="100%">
380 <pre class="PROGRAMLISTING">
381 int loadsomefile( struct client_state *csp )
382 int loadSomeFile( struct client_state *csp )
390 <h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file
393 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
395 <p>Use a descriptive parameter name in the function prototype in
396 header files. Use the same parameter name in the header file that you
397 use in the c file.</p>
399 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
401 <table class="c3" border="0" width="100%">
404 <pre class="PROGRAMLISTING">
405 (.h) extern int load_aclfile( struct client_state *csp );
406 (.c) int load_aclfile( struct client_state *csp )
412 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
414 <table class="c3" border="0" width="100%">
417 <pre class="PROGRAMLISTING">
418 (.h) extern int load_aclfile( struct client_state * ); or
419 (.h) extern int load_aclfile();
420 (.c) int load_aclfile( struct client_state *csp )
428 <h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and
431 <p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
439 <table class="c3" border="0" width="100%">
442 <pre class="PROGRAMLISTING">
443 (enumeration) : enum Boolean { FALSE, TRUE };
444 (#define) : #define DEFAULT_SIZE 100;
450 <p><span class="emphasis EMPHASIS c2">Note:</span> We have a standard
451 naming scheme for #defines that toggle a feature in the preprocessor:
452 FEATURE_>, where > is a short (preferably 1 or 2 word)
455 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
457 <table class="c3" border="0" 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 EMPHASIS c2">Explanation:</span></p>
477 <p>Spell common words out entirely (do not remove vowels).</p>
479 <p>Use only widely-known domain acronyms and abbreviations.
480 Capitalize all letters of an acronym.</p>
482 <p>Use underscore (_) to separate adjacent acronyms and
483 abbreviations. Never terminate a name with an underscore.</p>
485 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
487 <table class="c3" border="0" width="100%">
490 <pre class="PROGRAMLISTING">
491 #define USE_IMAGE_LIST 1
497 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
499 <table class="c3" border="0" width="100%">
502 <pre class="PROGRAMLISTING">
503 #define USE_IMG_LST 1 or
504 #define _USE_IMAGE_LIST 1 or
505 #define USE_IMAGE_LIST_ 1 or
506 #define use_image_list 1 or
507 #define UseImageList 1
516 <h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
519 <h3 class="SECT3"><a name="S16" id="S16">4.4.1. Put braces on a line
520 by themselves.</a></h3>
522 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
524 <p>The brace needs to be on a line all by itself, not at the end of
525 the statement. Curly braces should line up with the construct that
526 they're associated with. This practice makes it easier to identify
527 the opening and closing braces for a block.</p>
529 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
531 <table class="c3" border="0" width="100%">
534 <pre class="PROGRAMLISTING">
544 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
546 <p>if ( this == that ) { ... }</p>
550 <p>if ( this == that ) { ... }</p>
552 <p><span class="emphasis EMPHASIS c2">Note:</span> In the special
553 case that the if-statement is inside a loop, and it is trivial, i.e.
554 it tests for a condition that is obvious from the purpose of the
555 block, one-liners as above may optically preserve the loop structure
556 and make it easier to read.</p>
558 <p><span class="emphasis EMPHASIS c2">Status:</span>
559 developer-discretion.</p>
561 <p><span class="emphasis EMPHASIS c2">Example exception:</span></p>
563 <table class="c3" border="0" width="100%">
566 <pre class="PROGRAMLISTING">
567 while ( more lines are read )
569 /* Please document what is/is not a comment line here */
570 if ( it's a comment ) continue;
572 do_something( line );
581 <h3 class="SECT3"><a name="S17" id="S17">4.4.2. ALL control
582 statements should have a block</a></h3>
584 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
586 <p>Using braces to make a block will make your code more readable and
587 less prone to error. All control statements should have a block
590 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
592 <table class="c3" border="0" width="100%">
595 <pre class="PROGRAMLISTING">
606 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
608 <p>if ( this == that ) do_something(); do_something_else();</p>
612 <p>if ( this == that ) do_something();</p>
614 <p><span class="emphasis EMPHASIS c2">Note:</span> The first example
615 in "Instead of" will execute in a manner other than that which the
616 developer desired (per indentation). Using code braces would have
617 prevented this "feature". The "explanation" and "exception" from the
618 point above also applies.</p>
622 <h3 class="SECT3"><a name="S18" id="S18">4.4.3. Do not
623 belabor/blow-up boolean expressions</a></h3>
625 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
627 <table class="c3" border="0" width="100%">
630 <pre class="PROGRAMLISTING">
631 structure->flag = ( condition );
637 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
639 <p>if ( condition ) { structure->flag = 1; } else {
640 structure->flag = 0; }</p>
642 <p><span class="emphasis EMPHASIS c2">Note:</span> The former is
643 readable and concise. The later is wordy and inefficient. Please
644 assume that any developer new to the project has at least a "good"
645 knowledge of C/C++. (Hope I do not offend by that last comment ...
650 <h3 class="SECT3"><a name="S19" id="S19">4.4.4. Use white space
651 freely because it is free</a></h3>
653 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
655 <p>Make it readable. The notable exception to using white space
656 freely is listed in the next guideline.</p>
658 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
660 <table class="c3" border="0" width="100%">
663 <pre class="PROGRAMLISTING">
666 int another_value = 0;
667 int this_variable = 0;
669 if ( this_variable == this_variable )
671 first_value = old_value + ( ( some_value - another_value ) - whatever )
679 <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
680 around structure operators</a></h3>
682 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
684 <p>- structure pointer operator ( "->" ) - member operator ( "." )
685 - functions and parentheses</p>
687 <p>It is a general coding practice to put pointers, references, and
688 function parentheses next to names. With spaces, the connection
689 between the object and variable/function name is not as clear.</p>
691 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
693 <table class="c3" border="0" width="100%">
696 <pre class="PROGRAMLISTING">
697 a_struct->a_member;
705 <p><span class="emphasis EMPHASIS c2">Instead of:</span> a_struct
706 -> a_member; a_struct . a_member; function_name ();</p>
710 <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
711 of a function stand out</a></h3>
713 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
715 <table class="c3" border="0" width="100%">
718 <pre class="PROGRAMLISTING">
724 } /* -END- function1 */
729 } /* -END- function2 */
735 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
737 <p>int function1( ... ) { ...code... return( ret_code ); } int
738 function2( ... ) { }</p>
740 <p><span class="emphasis EMPHASIS c2">Note:</span> Use 1 blank line
741 before the closing brace and 2 lines afterward. This makes the end of
742 function standout to the most casual viewer. Although function
743 comments help separate functions, this is still a good coding
744 practice. In fact, I follow these rules when using blocks in "for",
745 "while", "do" loops, and long if {} statements too. After all
746 whitespace is free!</p>
748 <p><span class="emphasis EMPHASIS c2">Status:</span>
749 developer-discretion on the number of blank lines. Enforced is the
750 end of function comments.</p>
754 <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
757 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
759 <p>If some use 8 character TABs and some use 3 character TABs, the
760 code can look *very* ragged. So use 3 character indentions only. If
761 you like to use TABs, pass your code through a filter such as "expand
762 -t3" before checking in your code.</p>
764 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
766 <table class="c3" border="0" width="100%">
769 <pre class="PROGRAMLISTING">
770 static const char * const url_code_map[256] =
780 return( ALWAYS_TRUE );
784 return( HOW_DID_YOU_GET_HERE );
787 return( NEVER_GETS_HERE );
798 <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
801 <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
804 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
806 <p>Do not assume that the variables declared will not be used until
807 after they have been assigned a value somewhere else in the code.
808 Remove the chance of accidentally using an unassigned variable.</p>
810 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
812 <table class="c3" border="0" width="100%">
815 <pre class="PROGRAMLISTING">
824 <p><span class="emphasis EMPHASIS c2">Note:</span> It is much easier
825 to debug a SIGSEGV if the message says you are trying to access
826 memory address 00000000 and not 129FA012; or array_ptr[20] causes a
827 SIGSEV vs. array_ptr[0].</p>
829 <p><span class="emphasis EMPHASIS c2">Status:</span>
830 developer-discretion if and only if the variable is assigned a value
831 "shortly after" declaration.</p>
836 <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
839 <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
840 return a boolean as a question.</a></h3>
842 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
844 <p>Value should be phrased as a question that would logically be
845 answered as a true or false statement</p>
847 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
849 <table class="c3" border="0" width="100%">
852 <pre class="PROGRAMLISTING">
853 should_we_block_this();
863 <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
864 return type for a function.</a></h3>
866 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
868 <p>The default return for a function is an int. To avoid ambiguity,
869 create a return for a function when the return has a purpose, and
870 create a void return type if the function does not need to return
875 <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
876 calls when iterating by using variables</a></h3>
878 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
880 <p>It is easy to write the following code, and a clear argument can
881 be made that the code is easy to understand:</p>
883 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
885 <table class="c3" border="0" width="100%">
888 <pre class="PROGRAMLISTING">
889 for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
898 <p><span class="emphasis EMPHASIS c2">Note:</span> Unfortunately,
899 this makes a function call for each and every iteration. This
900 increases the overhead in the program, because the compiler has to
901 look up the function each time, call it, and return a value.
902 Depending on what occurs in the block_list_length() call, it might
903 even be creating and destroying structures with each iteration, even
904 though in each case it is comparing "cnt" to the same value, over and
905 over. Remember too - even a call to block_list_length() is a function
906 call, with the same overhead.</p>
908 <p>Instead of using a function call during the iterations, assign the
909 value to a variable, and evaluate using the variable.</p>
911 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
913 <table class="c3" border="0" width="100%">
916 <pre class="PROGRAMLISTING">
917 size_t len = block_list_length();
919 for ( size_t cnt = 0; cnt < len; cnt++ )
928 <p><span class="emphasis EMPHASIS c2">Exceptions:</span> if the value
929 of block_list_length() *may* change or could *potentially* change,
930 then you must code the function call in the for/while loop.</p>
934 <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
935 Const Reference</a></h3>
937 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
939 <p>This allows a developer to define a const pointer and call your
940 function. If your function does not have the const keyword, we may
941 not be able to use your function. Consider strcmp, if it were defined
942 as: extern int strcmp( char *s1, char *s2 );</p>
944 <p>I could then not use it to compare argv's in main: int main( int
945 argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); }</p>
947 <p>Both these pointers are *const*! If the c runtime library
948 maintainers do it, we should too.</p>
952 <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
955 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
957 <p>Most structures cannot fit onto a normal stack entry (i.e. they
958 are not 4 bytes or less). Aka, a function declaration like: int
959 load_aclfile( struct client_state csp )</p>
961 <p>would not work. So, to be consistent, we should declare all
962 prototypes with "pass by value": int load_aclfile( struct
963 client_state *csp )</p>
967 <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
970 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
972 <p>Your include statements should contain the file name without a
973 path. The path should be listed in the Makefile, using -I as
974 processor directive to search the indicated paths. An exception to
975 this would be for some proprietary software that utilizes a partial
976 path to distinguish their header files from system or other header
979 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
981 <table class="c3" border="0" width="100%">
984 <pre class="PROGRAMLISTING">
985 #include <iostream.h> /* This is not a local include */
986 #include "config.h" /* This IS a local include */
992 <p><span class="emphasis EMPHASIS c2">Exception:</span></p>
994 <table class="c3" border="0" width="100%">
997 <pre class="PROGRAMLISTING">
998 /* This is not a local include, but requires a path element. */
999 #include <sys/fileName.h>
1005 <p><span class="emphasis EMPHASIS c2">Note:</span> Please! do not add
1006 "-I." to the Makefile without a _very_ good reason. This duplicates
1007 the #include "file.h" behavior.</p>
1011 <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
1012 inclusion protection</a></h3>
1014 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1016 <p>Prevents compiler and linker errors resulting from redefinition of
1019 <p>Wrap each header file with the following syntax to prevent
1020 multiple inclusions of the file. Of course, replace PROJECT_H with
1021 your file name, with "." Changed to "_", and make it uppercase.</p>
1023 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1025 <table class="c3" border="0" width="100%">
1028 <pre class="PROGRAMLISTING">
1029 #ifndef PROJECT_H_INCLUDED
1030 #define PROJECT_H_INCLUDED
1032 #endif /* ndef PROJECT_H_INCLUDED */
1040 <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
1041 appropriate</a></h3>
1043 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1045 <p>If our headers are included from C++, they must declare our
1046 functions as `extern "C"`. This has no cost in C, but increases the
1047 potential re-usability of our code.</p>
1049 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1051 <table class="c3" border="0" width="100%">
1054 <pre class="PROGRAMLISTING">
1058 #endif /* def __cplusplus */
1060 ... function definitions here ...
1064 #endif /* def __cplusplus */
1072 <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
1073 Forward Struct Declaration Instead of Includes</a></h3>
1075 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1077 <p>Useful in headers that include pointers to other struct's.
1078 Modifications to excess header files may cause needless compiles.</p>
1080 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1082 <table class="c3" border="0" width="100%">
1085 <pre class="PROGRAMLISTING">
1086 /*********************************************************************
1087 * We're avoiding an include statement here!
1088 *********************************************************************/
1090 extern file_list *xyz;
1096 <p><span class="emphasis EMPHASIS c2">Note:</span> If you declare
1097 "file_list xyz;" (without the pointer), then including the proper
1098 header file is necessary. If you only want to prototype a pointer,
1099 however, the header file is unnecessary.</p>
1101 <p><span class="emphasis EMPHASIS c2">Status:</span> Use with
1107 <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
1111 <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
1114 <p><span class="emphasis EMPHASIS c2">Explanation</span></p>
1116 <p>Compiler warnings are meant to help you find bugs. You should turn
1117 on as many as possible. With GCC, the switch is "-Wall". Try and fix
1118 as many warnings as possible.</p>
1122 <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
1123 case for all switch statements</a></h3>
1125 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1127 <p>What you think is guaranteed is never really guaranteed. The value
1128 that you don't think you need to check is the one that someday will
1129 be passed. So, to protect yourself from the unknown, always have a
1130 default step in a switch statement.</p>
1132 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1134 <table class="c3" border="0" width="100%">
1137 <pre class="PROGRAMLISTING">
1138 switch( hash_string( cmd ) )
1140 case hash_actions_file :
1150 ... anomaly code goes here ...
1151 continue; / break; / exit( 1 ); / etc ...
1153 } /* end switch( hash_string( cmd ) ) */
1159 <p><span class="emphasis EMPHASIS c2">Note:</span> If you already
1160 have a default condition, you are obviously exempt from this point.
1161 Of note, most of the WIN32 code calls `DefWindowProc' after the
1162 switch statement. This API call *should* be included in a default
1165 <p><span class="emphasis EMPHASIS c2">Another Note:</span> This is
1166 not so much a readability issue as a robust programming issue. The
1167 "anomaly code goes here" may be no more than a print to the STDERR
1168 stream (as in load_config). Or it may really be an abort
1171 <p><span class="emphasis EMPHASIS c2">Status:</span> Programmer
1172 discretion is advised.</p>
1176 <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
1177 through cases in a switch statement.</a></h3>
1179 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1181 <p>In general, you will want to have a 'break' statement within each
1182 'case' of a switch statement. This allows for the code to be more
1183 readable and understandable, and furthermore can prevent unwanted
1184 surprises if someone else later gets creative and moves the code
1187 <p>The language allows you to plan the fall through from one case
1188 statement to another simply by omitting the break statement within
1189 the case statement. This feature does have benefits, but should only
1190 be used in rare cases. In general, use a break statement for each
1193 <p>If you choose to allow fall through, you should comment both the
1194 fact of the fall through and reason why you felt it was
1199 <h3 class="SECT3"><a name="S39" id="S39">4.7.4. Use 'long' or 'short'
1200 Instead of 'int'</a></h3>
1202 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1204 <p>On 32-bit platforms, int usually has the range of long. On 16-bit
1205 platforms, int has the range of short.</p>
1207 <p><span class="emphasis EMPHASIS c2">Status:</span> open-to-debate.
1208 In the case of most FSF projects (including X/GNU-Emacs), there are
1209 typedefs to int4, int8, int16, (or equivalence ... I forget the exact
1210 typedefs now). Should we add these to IJB now that we have a
1211 "configure" script?</p>
1215 <h3 class="SECT3"><a name="S40" id="S40">4.7.5. Don't mix size_t and
1216 other types</a></h3>
1218 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1220 <p>The type of size_t varies across platforms. Do not make
1221 assumptions about whether it is signed or unsigned, or about how long
1222 it is. Do not compare a size_t against another variable of a
1223 different type (or even against a constant) without casting one of
1228 <h3 class="SECT3"><a name="S41" id="S41">4.7.6. Declare each variable
1229 and struct on its own line.</a></h3>
1231 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1233 <p>It can be tempting to declare a series of variables all on one
1236 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1238 <table class="c3" border="0" width="100%">
1241 <pre class="PROGRAMLISTING">
1250 <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
1252 <p>long a, b, c;</p>
1254 <p><span class="emphasis EMPHASIS c2">Explanation:</span> - there is
1255 more room for comments on the individual variables - easier to add
1256 new variables without messing up the original ones - when searching
1257 on a variable to find its type, there is less clutter to "visually"
1260 <p><span class="emphasis EMPHASIS c2">Exceptions:</span> when you
1261 want to declare a bunch of loop variables or other trivial variables;
1262 feel free to declare them on one line. You should, although, provide
1263 a good comment on their functions.</p>
1265 <p><span class="emphasis EMPHASIS c2">Status:</span>
1266 developer-discretion.</p>
1270 <h3 class="SECT3"><a name="S42" id="S42">4.7.7. Use malloc/zalloc
1273 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1275 <p>Create a local struct (on the stack) if the variable will live and
1276 die within the context of one function call.</p>
1278 <p>Only "malloc" a struct (on the heap) if the variable's life will
1279 extend beyond the context of one function call.</p>
1281 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1283 <table class="c3" border="0" width="100%">
1286 <pre class="PROGRAMLISTING">
1287 If a function creates a struct and stores a pointer to it in a
1288 list, then it should definitely be allocated via `malloc'.
1296 <h3 class="SECT3"><a name="S43" id="S43">4.7.8. The Programmer Who
1297 Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
1299 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1301 <p>If you have to "malloc" an instance, you are responsible for
1302 insuring that the instance is `free'd, even if the deallocation event
1303 falls within some other programmer's code. You are also responsible
1304 for ensuring that deletion is timely (i.e. not too soon, not too
1305 late). This is known as "low-coupling" and is a "good thing (tm)".
1306 You may need to offer a free/unload/destructor type function to
1307 accommodate this.</p>
1309 <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1311 <table class="c3" border="0" width="100%">
1314 <pre class="PROGRAMLISTING">
1315 int load_re_filterfile( struct client_state *csp ) { ... }
1316 static void unload_re_filterfile( void *f ) { ... }
1322 <p><span class="emphasis EMPHASIS c2">Exceptions:</span></p>
1324 <p>The developer cannot be expected to provide `free'ing functions
1325 for C run-time library functions ... such as `strdup'.</p>
1327 <p><span class="emphasis EMPHASIS c2">Status:</span>
1328 developer-discretion. The "main" use of this standard is for
1329 allocating and freeing data structures (complex or nested).</p>
1333 <h3 class="SECT3"><a name="S44" id="S44">4.7.9. Add loaders to the
1334 `file_list' structure and in order</a></h3>
1336 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1338 <p>I have ordered all of the "blocker" file code to be in alpha
1339 order. It is easier to add/read new blockers when you expect a
1342 <p><span class="emphasis EMPHASIS c2">Note:</span> It may appear that
1343 the alpha order is broken in places by POPUP tests coming before PCRS
1344 tests. But since POPUPs can also be referred to as KILLPOPUPs, it is
1345 clear that it should come first.</p>
1349 <h3 class="SECT3"><a name="S45" id="S45">4.7.10. "Uncertain" new code
1350 and/or changes to existing code, use FIXME or XXX</a></h3>
1352 <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1354 <p>If you have enough confidence in new code or confidence in your
1355 changes, but are not *quite* sure of the repercussions, add this:</p>
1357 <p>/* FIXME: this code has a logic error on platform XYZ, *
1358 attempting to fix */ #ifdef PLATFORM ...changed code here...
1363 <p>/* FIXME: I think the original author really meant this... */
1364 ...changed code here...</p>
1368 <p>/* FIXME: new code that *may* break something else... */ ...new
1371 <p><span class="emphasis EMPHASIS c2">Note:</span> If you make it
1372 clear that this may or may not be a "good thing (tm)", it will be
1373 easier to identify and include in the project (or conversely exclude
1374 from the project).</p>
1379 <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
1380 files and function comment blocks:</a></h2>
1382 <p><span class="emphasis EMPHASIS c2">Example for file
1383 comments:</span></p>
1385 <table class="c3" border="0" width="100%">
1388 <pre class="PROGRAMLISTING">
1389 const char FILENAME_rcs[] = "$Id$";
1390 /*********************************************************************
1394 * Purpose : (Fill me in with a good description!)
1396 * Copyright : Written by and Copyright (C) 2001-2009
1397 * the Privoxy team. http://www.privoxy.org/
1399 * This program is free software; you can redistribute it
1400 * and/or modify it under the terms of the GNU General
1401 * Public License as published by the Free Software
1402 * Foundation; either version 2 of the License, or (at
1403 * your option) any later version.
1405 * This program is distributed in the hope that it will
1406 * be useful, but WITHOUT ANY WARRANTY; without even the
1407 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1408 * PARTICULAR PURPOSE. See the GNU General Public
1409 * License for more details.
1411 * The GNU General Public License should be included with
1412 * this file. If not, you can view it at
1413 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1414 * or write to the Free Software Foundation, Inc.,
1415 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1418 *********************************************************************/
1423 ...necessary include files for us to do our work...
1425 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1431 <p><span class="emphasis EMPHASIS c2">Note:</span> This declares the
1432 rcs variables that should be added to the "show-proxy-args" page. If
1433 this is a brand new creation by you, you are free to change the
1434 "Copyright" section to represent the rights you wish to maintain.</p>
1436 <p><span class="emphasis EMPHASIS c2">Note:</span> The formfeed
1437 character that is present right after the comment flower box is handy
1438 for (X|GNU)Emacs users to skip the verbiage and get to the heart of the
1439 code (via `forward-page' and `backward-page'). Please include it if you
1442 <p><span class="emphasis EMPHASIS c2">Example for file header
1443 comments:</span></p>
1445 <table class="c3" border="0" width="100%">
1448 <pre class="PROGRAMLISTING">
1451 #define FILENAME_H_VERSION "$Id$"
1452 /*********************************************************************
1456 * Purpose : (Fill me in with a good description!)
1458 * Copyright : Written by and Copyright (C) 2001-2009
1459 * the Privoxy team. http://www.privoxy.org/
1461 * This program is free software; you can redistribute it
1462 * and/or modify it under the terms of the GNU General
1463 * Public License as published by the Free Software
1464 * Foundation; either version 2 of the License, or (at
1465 * your option) any later version.
1467 * This program is distributed in the hope that it will
1468 * be useful, but WITHOUT ANY WARRANTY; without even the
1469 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1470 * PARTICULAR PURPOSE. See the GNU General Public
1471 * License for more details.
1473 * The GNU General Public License should be included with
1474 * this file. If not, you can view it at
1475 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1476 * or write to the Free Software Foundation, Inc.,
1477 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1480 *********************************************************************/
1483 #include "project.h"
1489 ... function headers here ...
1492 /* Revision control strings from this header and associated .c file */
1493 extern const char FILENAME_rcs[];
1494 extern const char FILENAME_h_rcs[];
1501 #endif /* ndef _FILENAME_H */
1513 <p><span class="emphasis EMPHASIS c2">Example for function
1514 comments:</span></p>
1516 <table class="c3" border="0" width="100%">
1519 <pre class="PROGRAMLISTING">
1520 /*********************************************************************
1522 * Function : FUNCTION_NAME
1524 * Description : (Fill me in with a good description!)
1527 * 1 : param1 = pointer to an important thing
1528 * 2 : x = pointer to something else
1530 * Returns : 0 => Ok, everything else is an error.
1532 *********************************************************************/
1533 int FUNCTION_NAME( void *param1, const char *x )
1544 <p><span class="emphasis EMPHASIS c2">Note:</span> If we all follow
1545 this practice, we should be able to parse our code to create a
1546 "self-documenting" web page.</p>
1550 <div class="NAVFOOTER">
1551 <hr class="c1" width="100%">
1553 <table summary="Footer navigation table" width="100%" border="0"
1554 cellpadding="0" cellspacing="0">
1556 <td width="33%" align="left" valign="top"><a href=
1557 "documentation.html" accesskey="P">Prev</a></td>
1559 <td width="34%" align="center" valign="top"><a href="index.html"
1560 accesskey="H">Home</a></td>
1562 <td width="33%" align="right" valign="top"><a href="testing.html"
1563 accesskey="N">Next</a></td>
1567 <td width="33%" align="left" valign="top">Documentation
1570 <td width="34%" align="center" valign="top"> </td>
1572 <td width="33%" align="right" valign="top">Testing Guidelines</td>