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 fellow Privoxy
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;
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;
684 <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
685 around structure operators</a></h3>
687 <p><span class="emphasis"><i class=
688 "EMPHASIS">Explanation:</i></span></p>
690 <p>- structure pointer operator ( "->" ) - member operator ( "." )
691 - functions and parentheses</p>
693 <p>It is a general coding practice to put pointers, references, and
694 function parentheses next to names. With spaces, the connection
695 between the object and variable/function name is not as clear.</p>
697 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
699 <table border="0" bgcolor="#E0E0E0" width="100%">
702 <pre class="PROGRAMLISTING">
703 a_struct->a_member;
711 <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
712 a_struct -> a_member; a_struct . a_member; function_name ();</p>
716 <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
717 of a function stand out</a></h3>
719 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
721 <table border="0" bgcolor="#E0E0E0" width="100%">
724 <pre class="PROGRAMLISTING">
730 } /* -END- function1 */
735 } /* -END- function2 */
741 <p><span class="emphasis"><i class="EMPHASIS">Instead
744 <p>int function1( ... ) { ...code... return(ret_code); } int
745 function2( ... ) { }</p>
747 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> Use 1
748 blank line before the closing brace and 2 lines afterward. This makes
749 the end of function standout to the most casual viewer. Although
750 function comments help separate functions, this is still a good
751 coding practice. In fact, I follow these rules when using blocks in
752 "for", "while", "do" loops, and long if {} statements too. After all
753 whitespace is free!</p>
755 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
756 developer-discretion on the number of blank lines. Enforced is the
757 end of function comments.</p>
761 <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
764 <p><span class="emphasis"><i class=
765 "EMPHASIS">Explanation:</i></span></p>
767 <p>If some use 8 character TABs and some use 3 character TABs, the
768 code can look *very* ragged. So use 3 character indentions only. If
769 you like to use TABs, pass your code through a filter such as "expand
770 -t3" before checking in your code.</p>
772 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
774 <table border="0" bgcolor="#E0E0E0" width="100%">
777 <pre class="PROGRAMLISTING">
778 static const char * const url_code_map[256] =
792 return HOW_DID_YOU_GET_HERE;
795 return NEVER_GETS_HERE;
806 <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
809 <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
812 <p><span class="emphasis"><i class=
813 "EMPHASIS">Explanation:</i></span></p>
815 <p>Do not assume that the variables declared will not be used until
816 after they have been assigned a value somewhere else in the code.
817 Remove the chance of accidentally using an unassigned variable.</p>
819 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
821 <table border="0" bgcolor="#E0E0E0" width="100%">
824 <pre class="PROGRAMLISTING">
833 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It is
834 much easier to debug a SIGSEGV if the message says you are trying to
835 access memory address 00000000 and not 129FA012; or array_ptr[20]
836 causes a SIGSEV vs. array_ptr[0].</p>
838 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
839 developer-discretion if and only if the variable is assigned a value
840 "shortly after" declaration.</p>
845 <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
848 <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
849 return a boolean as a question.</a></h3>
851 <p><span class="emphasis"><i class=
852 "EMPHASIS">Explanation:</i></span></p>
854 <p>Value should be phrased as a question that would logically be
855 answered as a true or false statement</p>
857 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
859 <table border="0" bgcolor="#E0E0E0" width="100%">
862 <pre class="PROGRAMLISTING">
863 should_we_block_this();
873 <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
874 return type for a function.</a></h3>
876 <p><span class="emphasis"><i class=
877 "EMPHASIS">Explanation:</i></span></p>
879 <p>The default return for a function is an int. To avoid ambiguity,
880 create a return for a function when the return has a purpose, and
881 create a void return type if the function does not need to return
886 <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
887 calls when iterating by using variables</a></h3>
889 <p><span class="emphasis"><i class=
890 "EMPHASIS">Explanation:</i></span></p>
892 <p>It is easy to write the following code, and a clear argument can
893 be made that the code is easy to understand:</p>
895 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
897 <table border="0" bgcolor="#E0E0E0" width="100%">
900 <pre class="PROGRAMLISTING">
901 for (size_t cnt = 0; cnt < block_list_length(); cnt++)
910 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
911 Unfortunately, this makes a function call for each and every
912 iteration. This increases the overhead in the program, because the
913 compiler has to look up the function each time, call it, and return a
914 value. Depending on what occurs in the block_list_length() call, it
915 might even be creating and destroying structures with each iteration,
916 even though in each case it is comparing "cnt" to the same value,
917 over and over. Remember too - even a call to block_list_length() is a
918 function call, with the same overhead.</p>
920 <p>Instead of using a function call during the iterations, assign the
921 value to a variable, and evaluate using the variable.</p>
923 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
925 <table border="0" bgcolor="#E0E0E0" width="100%">
928 <pre class="PROGRAMLISTING">
929 size_t len = block_list_length();
931 for (size_t cnt = 0; cnt < len; cnt++)
940 <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
941 if the value of block_list_length() *may* change or could
942 *potentially* change, then you must code the function call in the
947 <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
948 Const Reference</a></h3>
950 <p><span class="emphasis"><i class=
951 "EMPHASIS">Explanation:</i></span></p>
953 <p>This allows a developer to define a const pointer and call your
954 function. If your function does not have the const keyword, we may
955 not be able to use your function. Consider strcmp, if it were defined
956 as: extern int strcmp(char *s1, char *s2);</p>
958 <p>I could then not use it to compare argv's in main: int main(int
959 argc, const char *argv[]) { strcmp(argv[0], "privoxy"); }</p>
961 <p>Both these pointers are *const*! If the c runtime library
962 maintainers do it, we should too.</p>
966 <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
969 <p><span class="emphasis"><i class=
970 "EMPHASIS">Explanation:</i></span></p>
972 <p>Most structures cannot fit onto a normal stack entry (i.e. they
973 are not 4 bytes or less). Aka, a function declaration like: int
974 load_aclfile(struct client_state csp)</p>
976 <p>would not work. So, to be consistent, we should declare all
977 prototypes with "pass by value": int load_aclfile(struct client_state
982 <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
985 <p><span class="emphasis"><i class=
986 "EMPHASIS">Explanation:</i></span></p>
988 <p>Your include statements should contain the file name without a
989 path. The path should be listed in the Makefile, using -I as
990 processor directive to search the indicated paths. An exception to
991 this would be for some proprietary software that utilizes a partial
992 path to distinguish their header files from system or other header
995 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
997 <table border="0" bgcolor="#E0E0E0" width="100%">
1000 <pre class="PROGRAMLISTING">
1001 #include <iostream.h> /* This is not a local include */
1002 #include "config.h" /* This IS a local include */
1008 <p><span class="emphasis"><i class=
1009 "EMPHASIS">Exception:</i></span></p>
1011 <table border="0" bgcolor="#E0E0E0" width="100%">
1014 <pre class="PROGRAMLISTING">
1015 /* This is not a local include, but requires a path element. */
1016 #include <sys/fileName.h>
1022 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
1023 Please! do not add "-I." to the Makefile without a _very_ good
1024 reason. This duplicates the #include "file.h" behavior.</p>
1028 <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
1029 inclusion protection</a></h3>
1031 <p><span class="emphasis"><i class=
1032 "EMPHASIS">Explanation:</i></span></p>
1034 <p>Prevents compiler and linker errors resulting from redefinition of
1037 <p>Wrap each header file with the following syntax to prevent
1038 multiple inclusions of the file. Of course, replace PROJECT_H with
1039 your file name, with "." Changed to "_", and make it uppercase.</p>
1041 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1043 <table border="0" bgcolor="#E0E0E0" width="100%">
1046 <pre class="PROGRAMLISTING">
1047 #ifndef PROJECT_H_INCLUDED
1048 #define PROJECT_H_INCLUDED
1050 #endif /* ndef PROJECT_H_INCLUDED */
1058 <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
1059 appropriate</a></h3>
1061 <p><span class="emphasis"><i class=
1062 "EMPHASIS">Explanation:</i></span></p>
1064 <p>If our headers are included from C++, they must declare our
1065 functions as `extern "C"`. This has no cost in C, but increases the
1066 potential re-usability of our code.</p>
1068 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1070 <table border="0" bgcolor="#E0E0E0" width="100%">
1073 <pre class="PROGRAMLISTING">
1077 #endif /* def __cplusplus */
1079 ... function definitions here ...
1083 #endif /* def __cplusplus */
1091 <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
1092 Forward Struct Declaration Instead of Includes</a></h3>
1094 <p><span class="emphasis"><i class=
1095 "EMPHASIS">Explanation:</i></span></p>
1097 <p>Useful in headers that include pointers to other struct's.
1098 Modifications to excess header files may cause needless compiles.</p>
1100 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1102 <table border="0" bgcolor="#E0E0E0" width="100%">
1105 <pre class="PROGRAMLISTING">
1106 /*********************************************************************
1107 * We're avoiding an include statement here!
1108 *********************************************************************/
1110 extern file_list *xyz;
1116 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1117 declare "file_list xyz;" (without the pointer), then including the
1118 proper header file is necessary. If you only want to prototype a
1119 pointer, however, the header file is unnecessary.</p>
1121 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> Use
1122 with discretion.</p>
1127 <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
1131 <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
1134 <p><span class="emphasis"><i class=
1135 "EMPHASIS">Explanation</i></span></p>
1137 <p>Compiler warnings are meant to help you find bugs. You should turn
1138 on as many as possible. With GCC, the switch is "-Wall". Try and fix
1139 as many warnings as possible.</p>
1143 <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
1144 case for all switch statements</a></h3>
1146 <p><span class="emphasis"><i class=
1147 "EMPHASIS">Explanation:</i></span></p>
1149 <p>What you think is guaranteed is never really guaranteed. The value
1150 that you don't think you need to check is the one that someday will
1151 be passed. So, to protect yourself from the unknown, always have a
1152 default step in a switch statement.</p>
1154 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1156 <table border="0" bgcolor="#E0E0E0" width="100%">
1159 <pre class="PROGRAMLISTING">
1160 switch (hash_string(cmd))
1162 case hash_actions_file:
1172 ... anomaly code goes here ...
1173 continue; / break; / exit( 1 ); / etc ...
1175 } /* end switch (hash_string(cmd)) */
1181 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1182 already have a default condition, you are obviously exempt from this
1183 point. Of note, most of the WIN32 code calls `DefWindowProc' after
1184 the switch statement. This API call *should* be included in a default
1187 <p><span class="emphasis"><i class="EMPHASIS">Another
1188 Note:</i></span> This is not so much a readability issue as a robust
1189 programming issue. The "anomaly code goes here" may be no more than a
1190 print to the STDERR stream (as in load_config). Or it may really be
1191 an abort condition.</p>
1193 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1194 Programmer discretion is advised.</p>
1198 <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
1199 through cases in a switch statement.</a></h3>
1201 <p><span class="emphasis"><i class=
1202 "EMPHASIS">Explanation:</i></span></p>
1204 <p>In general, you will want to have a 'break' statement within each
1205 'case' of a switch statement. This allows for the code to be more
1206 readable and understandable, and furthermore can prevent unwanted
1207 surprises if someone else later gets creative and moves the code
1210 <p>The language allows you to plan the fall through from one case
1211 statement to another simply by omitting the break statement within
1212 the case statement. This feature does have benefits, but should only
1213 be used in rare cases. In general, use a break statement for each
1216 <p>If you choose to allow fall through, you should comment both the
1217 fact of the fall through and reason why you felt it was
1222 <h3 class="SECT3"><a name="S40" id="S40">4.7.4. Don't mix size_t and
1223 other types</a></h3>
1225 <p><span class="emphasis"><i class=
1226 "EMPHASIS">Explanation:</i></span></p>
1228 <p>The type of size_t varies across platforms. Do not make
1229 assumptions about whether it is signed or unsigned, or about how long
1230 it is. Do not compare a size_t against another variable of a
1231 different type (or even against a constant) without casting one of
1236 <h3 class="SECT3"><a name="S41" id="S41">4.7.5. Declare each variable
1237 and struct on its own line.</a></h3>
1239 <p><span class="emphasis"><i class=
1240 "EMPHASIS">Explanation:</i></span></p>
1242 <p>It can be tempting to declare a series of variables all on one
1245 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1247 <table border="0" bgcolor="#E0E0E0" width="100%">
1250 <pre class="PROGRAMLISTING">
1259 <p><span class="emphasis"><i class="EMPHASIS">Instead
1262 <p>long a, b, c;</p>
1264 <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span>
1265 - there is more room for comments on the individual variables -
1266 easier to add new variables without messing up the original ones -
1267 when searching on a variable to find its type, there is less clutter
1268 to "visually" eliminate</p>
1270 <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
1271 when you want to declare a bunch of loop variables or other trivial
1272 variables; feel free to declare them on one line. You should,
1273 although, provide a good comment on their functions.</p>
1275 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1276 developer-discretion.</p>
1280 <h3 class="SECT3"><a name="S42" id="S42">4.7.6. Use malloc/zalloc
1283 <p><span class="emphasis"><i class=
1284 "EMPHASIS">Explanation:</i></span></p>
1286 <p>Create a local struct (on the stack) if the variable will live and
1287 die within the context of one function call.</p>
1289 <p>Only "malloc" a struct (on the heap) if the variable's life will
1290 extend beyond the context of one function call.</p>
1292 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1294 <table border="0" bgcolor="#E0E0E0" width="100%">
1297 <pre class="PROGRAMLISTING">
1298 If a function creates a struct and stores a pointer to it in a
1299 list, then it should definitely be allocated via `malloc'.
1307 <h3 class="SECT3"><a name="S43" id="S43">4.7.7. The Programmer Who
1308 Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
1310 <p><span class="emphasis"><i class=
1311 "EMPHASIS">Explanation:</i></span></p>
1313 <p>If you have to "malloc" an instance, you are responsible for
1314 insuring that the instance is `free'd, even if the deallocation event
1315 falls within some other programmer's code. You are also responsible
1316 for ensuring that deletion is timely (i.e. not too soon, not too
1317 late). This is known as "low-coupling" and is a "good thing (tm)".
1318 You may need to offer a free/unload/destructor type function to
1319 accommodate this.</p>
1321 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1323 <table border="0" bgcolor="#E0E0E0" width="100%">
1326 <pre class="PROGRAMLISTING">
1327 int load_re_filterfile(struct client_state *csp) { ... }
1328 static void unload_re_filterfile(void *f) { ... }
1334 <p><span class="emphasis"><i class=
1335 "EMPHASIS">Exceptions:</i></span></p>
1337 <p>The developer cannot be expected to provide `free'ing functions
1338 for C run-time library functions ... such as `strdup'.</p>
1340 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1341 developer-discretion. The "main" use of this standard is for
1342 allocating and freeing data structures (complex or nested).</p>
1346 <h3 class="SECT3"><a name="S44" id="S44">4.7.8. Add loaders to the
1347 `file_list' structure and in order</a></h3>
1349 <p><span class="emphasis"><i class=
1350 "EMPHASIS">Explanation:</i></span></p>
1352 <p>I have ordered all of the "blocker" file code to be in alpha
1353 order. It is easier to add/read new blockers when you expect a
1356 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It may
1357 appear that the alpha order is broken in places by POPUP tests coming
1358 before PCRS tests. But since POPUPs can also be referred to as
1359 KILLPOPUPs, it is clear that it should come first.</p>
1363 <h3 class="SECT3"><a name="S45" id="S45">4.7.9. "Uncertain" new code
1364 and/or changes to existing code, use XXX</a></h3>
1366 <p><span class="emphasis"><i class=
1367 "EMPHASIS">Explanation:</i></span></p>
1369 <p>If you have enough confidence in new code or confidence in your
1370 changes, but are not *quite* sure of the repercussions, add this:</p>
1372 <p>/* XXX: this code has a logic error on platform XYZ, * attempting
1373 to fix */ #ifdef PLATFORM ...changed code here... #endif</p>
1377 <p>/* XXX: I think the original author really meant this... */
1378 ...changed code here...</p>
1382 <p>/* XXX: new code that *may* break something else... */ ...new code
1385 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1386 make it clear that this may or may not be a "good thing (tm)", it
1387 will be easier to identify and include in the project (or conversely
1388 exclude from the project).</p>
1393 <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
1394 files and function comment blocks:</a></h2>
1396 <p><span class="emphasis"><i class="EMPHASIS">Example for file
1397 comments:</i></span></p>
1399 <table border="0" bgcolor="#E0E0E0" width="100%">
1402 <pre class="PROGRAMLISTING">
1403 const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$";
1404 /*********************************************************************
1406 * File : $S<!-- Break CVS Substitution -->ource$
1408 * Purpose : (Fill me in with a good description!)
1410 * Copyright : Written by and Copyright (C) 2001-2009
1411 * the Privoxy team. https://www.privoxy.org/
1413 * This program is free software; you can redistribute it
1414 * and/or modify it under the terms of the GNU General
1415 * Public License as published by the Free Software
1416 * Foundation; either version 2 of the License, or (at
1417 * your option) any later version.
1419 * This program is distributed in the hope that it will
1420 * be useful, but WITHOUT ANY WARRANTY; without even the
1421 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1422 * PARTICULAR PURPOSE. See the GNU General Public
1423 * License for more details.
1425 * The GNU General Public License should be included with
1426 * this file. If not, you can view it at
1427 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1428 * or write to the Free Software Foundation, Inc.,
1429 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1432 *********************************************************************/
1437 ...necessary include files for us to do our work...
1439 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1445 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> This
1446 declares the rcs variables that should be added to the
1447 "show-proxy-args" page. If this is a brand new creation by you, you are
1448 free to change the "Copyright" section to represent the rights you wish
1451 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
1452 formfeed character that is present right after the comment flower box
1453 is handy for (X|GNU)Emacs users to skip the verbiage and get to the
1454 heart of the code (via `forward-page' and `backward-page'). Please
1455 include it if you can.</p>
1457 <p><span class="emphasis"><i class="EMPHASIS">Example for file header
1458 comments:</i></span></p>
1460 <table border="0" bgcolor="#E0E0E0" width="100%">
1463 <pre class="PROGRAMLISTING">
1466 #define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$"
1467 /*********************************************************************
1469 * File : $S<!-- Break CVS Substitution -->ource$
1471 * Purpose : (Fill me in with a good description!)
1473 * Copyright : Written by and Copyright (C) 2001-2009
1474 * the Privoxy team. https://www.privoxy.org/
1476 * This program is free software; you can redistribute it
1477 * and/or modify it under the terms of the GNU General
1478 * Public License as published by the Free Software
1479 * Foundation; either version 2 of the License, or (at
1480 * your option) any later version.
1482 * This program is distributed in the hope that it will
1483 * be useful, but WITHOUT ANY WARRANTY; without even the
1484 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1485 * PARTICULAR PURPOSE. See the GNU General Public
1486 * License for more details.
1488 * The GNU General Public License should be included with
1489 * this file. If not, you can view it at
1490 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1491 * or write to the Free Software Foundation, Inc.,
1492 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1495 *********************************************************************/
1498 #include "project.h"
1504 ... function headers here ...
1507 /* Revision control strings from this header and associated .c file */
1508 extern const char FILENAME_rcs[];
1509 extern const char FILENAME_h_rcs[];
1516 #endif /* ndef _FILENAME_H */
1528 <p><span class="emphasis"><i class="EMPHASIS">Example for function
1529 comments:</i></span></p>
1531 <table border="0" bgcolor="#E0E0E0" width="100%">
1534 <pre class="PROGRAMLISTING">
1535 /*********************************************************************
1537 * Function : FUNCTION_NAME
1539 * Description : (Fill me in with a good description!)
1542 * 1 : param1 = pointer to an important thing
1543 * 2 : x = pointer to something else
1545 * Returns : 0 => Ok, everything else is an error.
1547 *********************************************************************/
1548 int FUNCTION_NAME(void *param1, const char *x)
1559 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If we
1560 all follow this practice, we should be able to parse our code to create
1561 a "self-documenting" web page.</p>
1565 <div class="NAVFOOTER">
1566 <hr align="left" width="100%">
1568 <table summary="Footer navigation table" width="100%" border="0"
1569 cellpadding="0" cellspacing="0">
1571 <td width="33%" align="left" valign="top"><a href=
1572 "documentation.html" accesskey="P">Prev</a></td>
1574 <td width="34%" align="center" valign="top"><a href="index.html"
1575 accesskey="H">Home</a></td>
1577 <td width="33%" align="right" valign="top"><a href="testing.html"
1578 accesskey="N">Next</a></td>
1582 <td width="33%" align="left" valign="top">Documentation
1585 <td width="34%" align="center" valign="top"> </td>
1587 <td width="33%" align="right" valign="top">Testing Guidelines</td>