1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
2 "http://www.w3.org/TR/html4/loose.dtd">
5 <title>Coding Guidelines</title>
6 <meta name="GENERATOR" content=
7 "Modular DocBook HTML Stylesheet Version 1.79">
8 <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
9 <link rel="PREVIOUS" title="Documentation Guidelines" href=
11 <link rel="NEXT" title="Testing Guidelines" href="testing.html">
12 <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
13 <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
15 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
16 "#840084" alink="#0000FF">
17 <div class="NAVHEADER">
18 <table summary="Header navigation table" width="100%" border="0"
19 cellpadding="0" cellspacing="0">
21 <th colspan="3" align="center">Privoxy Developer Manual</th>
24 <td width="10%" align="left" valign="bottom"><a href=
25 "documentation.html" accesskey="P">Prev</a></td>
26 <td width="80%" align="center" valign="bottom"></td>
27 <td width="10%" align="right" valign="bottom"><a href="testing.html"
28 accesskey="N">Next</a></td>
31 <hr align="left" width="100%">
34 <h1 class="SECT1"><a name="CODING" id="CODING">4. Coding
37 <h2 class="SECT2"><a name="S1" id="S1">4.1. Introduction</a></h2>
38 <p>This set of standards is designed to make our lives easier. It is
39 developed with the simple goal of helping us keep the "new and improved
40 <span class="APPLICATION">Privoxy</span>" consistent and reliable. Thus
41 making maintenance easier and increasing chances of success of the
43 <p>And that of course comes back to us as individuals. If we can
44 increase our development and product efficiencies then we can solve
45 more of the request for changes/improvements and in general feel good
46 about ourselves. ;-></p>
49 <h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
51 <h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment,
53 <p><span class="emphasis"><i class=
54 "EMPHASIS">Explanation:</i></span></p>
55 <p>Comment as much as possible without commenting the obvious. For
56 example do not comment "variable_a is equal to variable_b". Instead
57 explain why variable_a should be equal to the variable_b. Just
58 because a person can read code does not mean they will understand why
59 or what is being done. A reader may spend a lot more time figuring
60 out what is going on when a simple comment or explanation would have
61 prevented the extra research. Please help your fellow Privoxy
63 <p>The comments will also help justify the intent of the code. If the
64 comment describes something different than what the code is doing
65 then maybe a programming error is occurring.</p>
66 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
67 <table border="0" bgcolor="#E0E0E0" width="100%">
70 <pre class="PROGRAMLISTING">
71 /* if page size greater than 1k ... */
72 if (page_length() > 1024)
74 ... "block" the page up ...
77 /* if page size is small, send it in blocks */
78 if (page_length() > 1024)
80 ... "block" the page up ...
83 This demonstrates 2 cases of "what not to do". The first is a
84 "syntax comment". The second is a comment that does not fit what
85 is actually being done.</pre>
91 <h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for
93 <p><span class="emphasis"><i class=
94 "EMPHASIS">Explanation:</i></span></p>
95 <p>Comments can help or they can clutter. They help when they are
96 differentiated from the code they describe. One line comments do not
97 offer effective separation between the comment and the code. Block
98 identifiers do, by surrounding the code with a clear, definable
100 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
101 <table border="0" bgcolor="#E0E0E0" width="100%">
104 <pre class="PROGRAMLISTING">
105 /*********************************************************************
106 * This will stand out clearly in your code!
107 *********************************************************************/
108 if (this_variable == that_variable)
110 do_something_very_important();
114 /* unfortunately, this may not */
115 if (this_variable == that_variable)
117 do_something_very_important();
121 if (this_variable == that_variable) /* this may not either */
123 do_something_very_important();
128 <p><span class="emphasis"><i class=
129 "EMPHASIS">Exception:</i></span></p>
130 <p>If you are trying to add a small logic comment and do not wish to
131 "disrupt" the flow of the code, feel free to use a 1 line comment
132 which is NOT on the same line as the code.</p>
135 <h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their
137 <p><span class="emphasis"><i class=
138 "EMPHASIS">Explanation:</i></span></p>
139 <p>It goes back to the question of readability. If the comment is on
140 the same line as the code it will be harder to read than the comment
141 that is on its own line.</p>
142 <p>There are three exceptions to this rule, which should be violated
143 freely and often: during the definition of variables, at the end of
144 closing braces, when used to comment parameters.</p>
145 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
146 <table border="0" bgcolor="#E0E0E0" width="100%">
149 <pre class="PROGRAMLISTING">
150 /*********************************************************************
151 * This will stand out clearly in your code,
152 * But the second example won't.
153 *********************************************************************/
154 if (this_variable == this_variable)
156 do_something_very_important();
159 if (this_variable == this_variable) /*can you see me?*/
161 do_something_very_important(); /*not easily*/
165 /*********************************************************************
166 * But, the encouraged exceptions:
167 *********************************************************************/
168 int urls_read = 0; /* # of urls read + rejected */
169 int urls_rejected = 0; /* # of urls rejected */
173 do_something_very_important();
177 short do_something_very_important(
178 short firstparam, /* represents something */
179 short nextparam /* represents something else */ )
183 } /* -END- do_something_very_important */</pre>
189 <h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical
191 <p><span class="emphasis"><i class=
192 "EMPHASIS">Explanation:</i></span></p>
193 <p>Logical steps should be commented to help others follow the intent
194 of the written code and comments will make the code more
196 <p>If you have 25 lines of code without a comment, you should
197 probably go back into it to see where you forgot to put one.</p>
198 <p>Most "for", "while", "do", etc... loops _probably_ need a comment.
199 After all, these are usually major logic containers.</p>
202 <h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions
204 <p><span class="emphasis"><i class=
205 "EMPHASIS">Explanation:</i></span></p>
206 <p>A reader of the code should be able to look at the comments just
207 prior to the beginning of a function and discern the reason for its
208 existence and the consequences of using it. The reader should not
209 have to read through the code to determine if a given function is
210 safe for a desired use. The proper information thoroughly presented
211 at the introduction of a function not only saves time for subsequent
212 maintenance or debugging, it more importantly aids in code reuse by
213 allowing a user to determine the safety and applicability of any
214 function for the problem at hand. As a result of such benefits, all
215 functions should contain the information presented in the addendum
216 section of this document.</p>
219 <h3 class="SECT3"><a name="S8" id="S8">4.2.6. Comment at the end of
220 braces if the content is more than one screen length</a></h3>
221 <p><span class="emphasis"><i class=
222 "EMPHASIS">Explanation:</i></span></p>
223 <p>Each closing brace should be followed on the same line by a
224 comment that describes the origination of the brace if the original
225 brace is off of the screen, or otherwise far away from the closing
226 brace. This will simplify the debugging, maintenance, and readability
228 <p>As a suggestion , use the following flags to make the comment and
229 its brace more readable:</p>
230 <p>use following a closing brace: } /* -END- if() or while () or
232 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
233 <table border="0" bgcolor="#E0E0E0" width="100%">
236 <pre class="PROGRAMLISTING">if (1 == X)
238 do_something_very_important();
239 ...some long list of commands...
240 } /* -END- if x is 1 */
246 do_something_very_important();
247 ...some long list of commands...
248 } /* -END- if (1 == X) */</pre>
255 <h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
257 <h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable
259 <p><span class="emphasis"><i class=
260 "EMPHASIS">Explanation:</i></span></p>
261 <p>Use all lowercase, and separate words via an underscore ('_'). Do
262 not start an identifier with an underscore. (ANSI C reserves these
263 for use by the compiler and system headers.) Do not use identifiers
264 which are reserved in ANSI C++. (E.g. template, class, true, false,
265 ...). This is in case we ever decide to port Privoxy to C++.</p>
266 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
267 <table border="0" bgcolor="#E0E0E0" width="100%">
270 <pre class="PROGRAMLISTING">int ms_iis5_hack = 0;</pre>
274 <p><span class="emphasis"><i class="EMPHASIS">Instead
276 <table border="0" bgcolor="#E0E0E0" width="100%">
279 <pre class="PROGRAMLISTING">
280 int msiis5hack = 0; int msIis5Hack = 0;</pre>
286 <h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function
288 <p><span class="emphasis"><i class=
289 "EMPHASIS">Explanation:</i></span></p>
290 <p>Use all lowercase, and separate words via an underscore ('_'). Do
291 not start an identifier with an underscore. (ANSI C reserves these
292 for use by the compiler and system headers.) Do not use identifiers
293 which are reserved in ANSI C++. (E.g. template, class, true, false,
294 ...). This is in case we ever decide to port Privoxy to C++.</p>
295 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
296 <table border="0" bgcolor="#E0E0E0" width="100%">
299 <pre class="PROGRAMLISTING">
300 int load_some_file(struct client_state *csp)</pre>
304 <p><span class="emphasis"><i class="EMPHASIS">Instead
306 <table border="0" bgcolor="#E0E0E0" width="100%">
309 <pre class="PROGRAMLISTING">
310 int loadsomefile(struct client_state *csp)
311 int loadSomeFile(struct client_state *csp)</pre>
317 <h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file
319 <p><span class="emphasis"><i class=
320 "EMPHASIS">Explanation:</i></span></p>
321 <p>Use a descriptive parameter name in the function prototype in
322 header files. Use the same parameter name in the header file that you
323 use in the c file.</p>
324 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
325 <table border="0" bgcolor="#E0E0E0" width="100%">
328 <pre class="PROGRAMLISTING">
329 (.h) extern int load_aclfile(struct client_state *csp);
330 (.c) int load_aclfile(struct client_state *csp)</pre>
334 <p><span class="emphasis"><i class="EMPHASIS">Instead
336 <table border="0" bgcolor="#E0E0E0" width="100%">
339 <pre class="PROGRAMLISTING">
340 (.h) extern int load_aclfile(struct client_state *); or
341 (.h) extern int load_aclfile();
342 (.c) int load_aclfile(struct client_state *csp)</pre>
348 <h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and
350 <p><span class="emphasis"><i class=
351 "EMPHASIS">Explanation:</i></span></p>
352 <p>Use all capital letters, with underscores between words. Do not
353 start an identifier with an underscore. (ANSI C reserves these for
354 use by the compiler and system headers.)</p>
355 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
356 <table border="0" bgcolor="#E0E0E0" width="100%">
359 <pre class="PROGRAMLISTING">
360 (enumeration) : enum Boolean {FALSE, TRUE};
361 (#define) : #define DEFAULT_SIZE 100;</pre>
365 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> We
366 have a standard naming scheme for #defines that toggle a feature in
367 the preprocessor: FEATURE_>, where > is a short (preferably 1
368 or 2 word) description.</p>
369 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
370 <table border="0" bgcolor="#E0E0E0" width="100%">
373 <pre class="PROGRAMLISTING">#define FEATURE_FORCE 1
376 #define FORCE_PREFIX blah
377 #endif /* def FEATURE_FORCE */</pre>
383 <h3 class="SECT3"><a name="S14" id="S14">4.3.5. Constants</a></h3>
384 <p><span class="emphasis"><i class=
385 "EMPHASIS">Explanation:</i></span></p>
386 <p>Spell common words out entirely (do not remove vowels).</p>
387 <p>Use only widely-known domain acronyms and abbreviations.
388 Capitalize all letters of an acronym.</p>
389 <p>Use underscore (_) to separate adjacent acronyms and
390 abbreviations. Never terminate a name with an underscore.</p>
391 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
392 <table border="0" bgcolor="#E0E0E0" width="100%">
395 <pre class="PROGRAMLISTING">#define USE_IMAGE_LIST 1</pre>
399 <p><span class="emphasis"><i class="EMPHASIS">Instead
401 <table border="0" bgcolor="#E0E0E0" width="100%">
404 <pre class="PROGRAMLISTING">#define USE_IMG_LST 1 or
405 #define _USE_IMAGE_LIST 1 or
406 #define USE_IMAGE_LIST_ 1 or
407 #define use_image_list 1 or
408 #define UseImageList 1</pre>
415 <h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
417 <h3 class="SECT3"><a name="S16" id="S16">4.4.1. Put braces on a line
418 by themselves.</a></h3>
419 <p><span class="emphasis"><i class=
420 "EMPHASIS">Explanation:</i></span></p>
421 <p>The brace needs to be on a line all by itself, not at the end of
422 the statement. Curly braces should line up with the construct that
423 they're associated with. This practice makes it easier to identify
424 the opening and closing braces for a block.</p>
425 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
426 <table border="0" bgcolor="#E0E0E0" width="100%">
429 <pre class="PROGRAMLISTING">if (this == that)
436 <p><span class="emphasis"><i class="EMPHASIS">Instead
438 <p>if (this == that) { ... }</p>
440 <p>if (this == that) { ... }</p>
441 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> In the
442 special case that the if-statement is inside a loop, and it is
443 trivial, i.e. it tests for a condition that is obvious from the
444 purpose of the block, one-liners as above may optically preserve the
445 loop structure and make it easier to read.</p>
446 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
447 developer-discretion.</p>
448 <p><span class="emphasis"><i class="EMPHASIS">Example
449 exception:</i></span></p>
450 <table border="0" bgcolor="#E0E0E0" width="100%">
453 <pre class="PROGRAMLISTING">while (more lines are read)
455 /* Please document what is/is not a comment line here */
456 if (it's a comment) continue;
465 <h3 class="SECT3"><a name="S17" id="S17">4.4.2. ALL control
466 statements should have a block</a></h3>
467 <p><span class="emphasis"><i class=
468 "EMPHASIS">Explanation:</i></span></p>
469 <p>Using braces to make a block will make your code more readable and
470 less prone to error. All control statements should have a block
472 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
473 <table border="0" bgcolor="#E0E0E0" width="100%">
476 <pre class="PROGRAMLISTING">if (this == that)
484 <p><span class="emphasis"><i class="EMPHASIS">Instead
486 <p>if (this == that) do_something(); do_something_else();</p>
488 <p>if (this == that) do_something();</p>
489 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
490 first example in "Instead of" will execute in a manner other than
491 that which the developer desired (per indentation). Using code braces
492 would have prevented this "feature". The "explanation" and
493 "exception" from the point above also applies.</p>
496 <h3 class="SECT3"><a name="S18" id="S18">4.4.3. Do not
497 belabor/blow-up boolean expressions</a></h3>
498 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
499 <table border="0" bgcolor="#E0E0E0" width="100%">
502 <pre class="PROGRAMLISTING">
503 structure->flag = (condition);</pre>
507 <p><span class="emphasis"><i class="EMPHASIS">Instead
509 <p>if (condition) { structure->flag = 1; } else {
510 structure->flag = 0; }</p>
511 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
512 former is readable and concise. The later is wordy and inefficient.
513 Please assume that any developer new to the project has at least a
514 "good" knowledge of C/C++. (Hope I do not offend by that last comment
518 <h3 class="SECT3"><a name="S19" id="S19">4.4.4. Use white space
519 freely because it is free</a></h3>
520 <p><span class="emphasis"><i class=
521 "EMPHASIS">Explanation:</i></span></p>
522 <p>Make it readable. The notable exception to using white space
523 freely is listed in the next guideline.</p>
524 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
525 <table border="0" bgcolor="#E0E0E0" width="100%">
528 <pre class="PROGRAMLISTING">int first_value = 0;
530 int another_value = 0;
531 int this_variable = 0;</pre>
537 <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
538 around structure operators</a></h3>
539 <p><span class="emphasis"><i class=
540 "EMPHASIS">Explanation:</i></span></p>
541 <p>- structure pointer operator ( "->" ) - member operator ( "." )
542 - functions and parentheses</p>
543 <p>It is a general coding practice to put pointers, references, and
544 function parentheses next to names. With spaces, the connection
545 between the object and variable/function name is not as clear.</p>
546 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
547 <table border="0" bgcolor="#E0E0E0" width="100%">
550 <pre class="PROGRAMLISTING">a_struct->a_member;
552 function_name();</pre>
556 <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
557 a_struct -> a_member; a_struct . a_member; function_name ();</p>
560 <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
561 of a function stand out</a></h3>
562 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
563 <table border="0" bgcolor="#E0E0E0" width="100%">
566 <pre class="PROGRAMLISTING">int function1( ... )
571 } /* -END- function1 */
576 } /* -END- function2 */</pre>
580 <p><span class="emphasis"><i class="EMPHASIS">Instead
582 <p>int function1( ... ) { ...code... return(ret_code); } int
583 function2( ... ) { }</p>
584 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> Use 1
585 blank line before the closing brace and 2 lines afterward. This makes
586 the end of function standout to the most casual viewer. Although
587 function comments help separate functions, this is still a good
588 coding practice. In fact, I follow these rules when using blocks in
589 "for", "while", "do" loops, and long if {} statements too. After all
590 whitespace is free!</p>
591 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
592 developer-discretion on the number of blank lines. Enforced is the
593 end of function comments.</p>
596 <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
598 <p><span class="emphasis"><i class=
599 "EMPHASIS">Explanation:</i></span></p>
600 <p>If some use 8 character TABs and some use 3 character TABs, the
601 code can look *very* ragged. So use 3 character indentions only. If
602 you like to use TABs, pass your code through a filter such as "expand
603 -t3" before checking in your code.</p>
604 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
605 <table border="0" bgcolor="#E0E0E0" width="100%">
608 <pre class="PROGRAMLISTING">
609 static const char * const url_code_map[256] =
623 return HOW_DID_YOU_GET_HERE;
626 return NEVER_GETS_HERE;
635 <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
637 <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
639 <p><span class="emphasis"><i class=
640 "EMPHASIS">Explanation:</i></span></p>
641 <p>Do not assume that the variables declared will not be used until
642 after they have been assigned a value somewhere else in the code.
643 Remove the chance of accidentally using an unassigned variable.</p>
644 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
645 <table border="0" bgcolor="#E0E0E0" width="100%">
648 <pre class="PROGRAMLISTING">short a_short = 0;
650 struct *ptr = NULL;</pre>
654 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It is
655 much easier to debug a SIGSEGV if the message says you are trying to
656 access memory address 00000000 and not 129FA012; or array_ptr[20]
657 causes a SIGSEV vs. array_ptr[0].</p>
658 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
659 developer-discretion if and only if the variable is assigned a value
660 "shortly after" declaration.</p>
664 <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
666 <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
667 return a boolean as a question.</a></h3>
668 <p><span class="emphasis"><i class=
669 "EMPHASIS">Explanation:</i></span></p>
670 <p>Value should be phrased as a question that would logically be
671 answered as a true or false statement</p>
672 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
673 <table border="0" bgcolor="#E0E0E0" width="100%">
676 <pre class="PROGRAMLISTING">should_we_block_this();
678 is_web_page_blank();</pre>
684 <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
685 return type for a function.</a></h3>
686 <p><span class="emphasis"><i class=
687 "EMPHASIS">Explanation:</i></span></p>
688 <p>The default return for a function is an int. To avoid ambiguity,
689 create a return for a function when the return has a purpose, and
690 create a void return type if the function does not need to return
694 <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
695 calls when iterating by using variables</a></h3>
696 <p><span class="emphasis"><i class=
697 "EMPHASIS">Explanation:</i></span></p>
698 <p>It is easy to write the following code, and a clear argument can
699 be made that the code is easy to understand:</p>
700 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
701 <table border="0" bgcolor="#E0E0E0" width="100%">
704 <pre class="PROGRAMLISTING">
705 for (size_t cnt = 0; cnt < block_list_length(); cnt++)
712 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
713 Unfortunately, this makes a function call for each and every
714 iteration. This increases the overhead in the program, because the
715 compiler has to look up the function each time, call it, and return a
716 value. Depending on what occurs in the block_list_length() call, it
717 might even be creating and destroying structures with each iteration,
718 even though in each case it is comparing "cnt" to the same value,
719 over and over. Remember too - even a call to block_list_length() is a
720 function call, with the same overhead.</p>
721 <p>Instead of using a function call during the iterations, assign the
722 value to a variable, and evaluate using the variable.</p>
723 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
724 <table border="0" bgcolor="#E0E0E0" width="100%">
727 <pre class="PROGRAMLISTING">size_t len = block_list_length();
729 for (size_t cnt = 0; cnt < len; cnt++)
736 <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
737 if the value of block_list_length() *may* change or could
738 *potentially* change, then you must code the function call in the
742 <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
743 Const Reference</a></h3>
744 <p><span class="emphasis"><i class=
745 "EMPHASIS">Explanation:</i></span></p>
746 <p>This allows a developer to define a const pointer and call your
747 function. If your function does not have the const keyword, we may
748 not be able to use your function. Consider strcmp, if it were defined
749 as: extern int strcmp(char *s1, char *s2);</p>
750 <p>I could then not use it to compare argv's in main: int main(int
751 argc, const char *argv[]) { strcmp(argv[0], "privoxy"); }</p>
752 <p>Both these pointers are *const*! If the c runtime library
753 maintainers do it, we should too.</p>
756 <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
758 <p><span class="emphasis"><i class=
759 "EMPHASIS">Explanation:</i></span></p>
760 <p>Most structures cannot fit onto a normal stack entry (i.e. they
761 are not 4 bytes or less). Aka, a function declaration like: int
762 load_aclfile(struct client_state csp)</p>
763 <p>would not work. So, to be consistent, we should declare all
764 prototypes with "pass by value": int load_aclfile(struct client_state
768 <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
770 <p><span class="emphasis"><i class=
771 "EMPHASIS">Explanation:</i></span></p>
772 <p>Your include statements should contain the file name without a
773 path. The path should be listed in the Makefile, using -I as
774 processor directive to search the indicated paths. An exception to
775 this would be for some proprietary software that utilizes a partial
776 path to distinguish their header files from system or other header
778 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
779 <table border="0" bgcolor="#E0E0E0" width="100%">
782 <pre class="PROGRAMLISTING">
783 #include <iostream.h> /* This is not a local include */
784 #include "config.h" /* This IS a local include */</pre>
788 <p><span class="emphasis"><i class=
789 "EMPHASIS">Exception:</i></span></p>
790 <table border="0" bgcolor="#E0E0E0" width="100%">
793 <pre class="PROGRAMLISTING">
794 /* This is not a local include, but requires a path element. */
795 #include <sys/fileName.h></pre>
799 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
800 Please! do not add "-I." to the Makefile without a _very_ good
801 reason. This duplicates the #include "file.h" behavior.</p>
804 <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
805 inclusion protection</a></h3>
806 <p><span class="emphasis"><i class=
807 "EMPHASIS">Explanation:</i></span></p>
808 <p>Prevents compiler and linker errors resulting from redefinition of
810 <p>Wrap each header file with the following syntax to prevent
811 multiple inclusions of the file. Of course, replace PROJECT_H with
812 your file name, with "." Changed to "_", and make it uppercase.</p>
813 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
814 <table border="0" bgcolor="#E0E0E0" width="100%">
817 <pre class="PROGRAMLISTING">#ifndef PROJECT_H_INCLUDED
818 #define PROJECT_H_INCLUDED
820 #endif /* ndef PROJECT_H_INCLUDED */</pre>
826 <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
828 <p><span class="emphasis"><i class=
829 "EMPHASIS">Explanation:</i></span></p>
830 <p>If our headers are included from C++, they must declare our
831 functions as `extern "C"`. This has no cost in C, but increases the
832 potential re-usability of our code.</p>
833 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
834 <table border="0" bgcolor="#E0E0E0" width="100%">
837 <pre class="PROGRAMLISTING">#ifdef __cplusplus
840 #endif /* def __cplusplus */
842 ... function definitions here ...
846 #endif /* def __cplusplus */</pre>
852 <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
853 Forward Struct Declaration Instead of Includes</a></h3>
854 <p><span class="emphasis"><i class=
855 "EMPHASIS">Explanation:</i></span></p>
856 <p>Useful in headers that include pointers to other struct's.
857 Modifications to excess header files may cause needless compiles.</p>
858 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
859 <table border="0" bgcolor="#E0E0E0" width="100%">
862 <pre class="PROGRAMLISTING">
863 /*********************************************************************
864 * We're avoiding an include statement here!
865 *********************************************************************/
867 extern file_list *xyz;</pre>
871 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
872 declare "file_list xyz;" (without the pointer), then including the
873 proper header file is necessary. If you only want to prototype a
874 pointer, however, the header file is unnecessary.</p>
875 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> Use
880 <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
883 <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
885 <p><span class="emphasis"><i class=
886 "EMPHASIS">Explanation</i></span></p>
887 <p>Compiler warnings are meant to help you find bugs. You should turn
888 on as many as possible. With GCC, the switch is "-Wall". Try and fix
889 as many warnings as possible.</p>
892 <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
893 case for all switch statements</a></h3>
894 <p><span class="emphasis"><i class=
895 "EMPHASIS">Explanation:</i></span></p>
896 <p>What you think is guaranteed is never really guaranteed. The value
897 that you don't think you need to check is the one that someday will
898 be passed. So, to protect yourself from the unknown, always have a
899 default step in a switch statement.</p>
900 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
901 <table border="0" bgcolor="#E0E0E0" width="100%">
904 <pre class="PROGRAMLISTING">switch (hash_string(cmd))
906 case hash_actions_file:
916 ... anomaly code goes here ...
917 continue; / break; / exit( 1 ); / etc ...
919 } /* end switch (hash_string(cmd)) */</pre>
923 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
924 already have a default condition, you are obviously exempt from this
925 point. Of note, most of the WIN32 code calls `DefWindowProc' after
926 the switch statement. This API call *should* be included in a default
928 <p><span class="emphasis"><i class="EMPHASIS">Another
929 Note:</i></span> This is not so much a readability issue as a robust
930 programming issue. The "anomaly code goes here" may be no more than a
931 print to the STDERR stream (as in load_config). Or it may really be
932 an abort condition.</p>
933 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
934 Programmer discretion is advised.</p>
937 <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
938 through cases in a switch statement.</a></h3>
939 <p><span class="emphasis"><i class=
940 "EMPHASIS">Explanation:</i></span></p>
941 <p>In general, you will want to have a 'break' statement within each
942 'case' of a switch statement. This allows for the code to be more
943 readable and understandable, and furthermore can prevent unwanted
944 surprises if someone else later gets creative and moves the code
946 <p>The language allows you to plan the fall through from one case
947 statement to another simply by omitting the break statement within
948 the case statement. This feature does have benefits, but should only
949 be used in rare cases. In general, use a break statement for each
951 <p>If you choose to allow fall through, you should comment both the
952 fact of the fall through and reason why you felt it was
956 <h3 class="SECT3"><a name="S40" id="S40">4.7.4. Don't mix size_t and
958 <p><span class="emphasis"><i class=
959 "EMPHASIS">Explanation:</i></span></p>
960 <p>The type of size_t varies across platforms. Do not make
961 assumptions about whether it is signed or unsigned, or about how long
962 it is. Do not compare a size_t against another variable of a
963 different type (or even against a constant) without casting one of
967 <h3 class="SECT3"><a name="S41" id="S41">4.7.5. Declare each variable
968 and struct on its own line.</a></h3>
969 <p><span class="emphasis"><i class=
970 "EMPHASIS">Explanation:</i></span></p>
971 <p>It can be tempting to declare a series of variables all on one
973 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
974 <table border="0" bgcolor="#E0E0E0" width="100%">
977 <pre class="PROGRAMLISTING">long a = 0;
983 <p><span class="emphasis"><i class="EMPHASIS">Instead
986 <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span>
987 - there is more room for comments on the individual variables -
988 easier to add new variables without messing up the original ones -
989 when searching on a variable to find its type, there is less clutter
990 to "visually" eliminate</p>
991 <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
992 when you want to declare a bunch of loop variables or other trivial
993 variables; feel free to declare them on one line. You should,
994 although, provide a good comment on their functions.</p>
995 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
996 developer-discretion.</p>
999 <h3 class="SECT3"><a name="S42" id="S42">4.7.6. Use malloc/zalloc
1001 <p><span class="emphasis"><i class=
1002 "EMPHASIS">Explanation:</i></span></p>
1003 <p>Create a local struct (on the stack) if the variable will live and
1004 die within the context of one function call.</p>
1005 <p>Only "malloc" a struct (on the heap) if the variable's life will
1006 extend beyond the context of one function call.</p>
1007 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1008 <table border="0" bgcolor="#E0E0E0" width="100%">
1011 <pre class="PROGRAMLISTING">
1012 If a function creates a struct and stores a pointer to it in a
1013 list, then it should definitely be allocated via `malloc'.</pre>
1019 <h3 class="SECT3"><a name="S43" id="S43">4.7.7. The Programmer Who
1020 Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
1021 <p><span class="emphasis"><i class=
1022 "EMPHASIS">Explanation:</i></span></p>
1023 <p>If you have to "malloc" an instance, you are responsible for
1024 insuring that the instance is `free'd, even if the deallocation event
1025 falls within some other programmer's code. You are also responsible
1026 for ensuring that deletion is timely (i.e. not too soon, not too
1027 late). This is known as "low-coupling" and is a "good thing (tm)".
1028 You may need to offer a free/unload/destructor type function to
1029 accommodate this.</p>
1030 <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1031 <table border="0" bgcolor="#E0E0E0" width="100%">
1034 <pre class="PROGRAMLISTING">
1035 int load_re_filterfile(struct client_state *csp) { ... }
1036 static void unload_re_filterfile(void *f) { ... }</pre>
1040 <p><span class="emphasis"><i class=
1041 "EMPHASIS">Exceptions:</i></span></p>
1042 <p>The developer cannot be expected to provide `free'ing functions
1043 for C run-time library functions ... such as `strdup'.</p>
1044 <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1045 developer-discretion. The "main" use of this standard is for
1046 allocating and freeing data structures (complex or nested).</p>
1049 <h3 class="SECT3"><a name="S44" id="S44">4.7.8. Add loaders to the
1050 `file_list' structure and in order</a></h3>
1051 <p><span class="emphasis"><i class=
1052 "EMPHASIS">Explanation:</i></span></p>
1053 <p>I have ordered all of the "blocker" file code to be in alpha
1054 order. It is easier to add/read new blockers when you expect a
1056 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It may
1057 appear that the alpha order is broken in places by POPUP tests coming
1058 before PCRS tests. But since POPUPs can also be referred to as
1059 KILLPOPUPs, it is clear that it should come first.</p>
1062 <h3 class="SECT3"><a name="S45" id="S45">4.7.9. "Uncertain" new code
1063 and/or changes to existing code, use XXX</a></h3>
1064 <p><span class="emphasis"><i class=
1065 "EMPHASIS">Explanation:</i></span></p>
1066 <p>If you have enough confidence in new code or confidence in your
1067 changes, but are not *quite* sure of the repercussions, add this:</p>
1068 <p>/* XXX: this code has a logic error on platform XYZ, * attempting
1069 to fix */ #ifdef PLATFORM ...changed code here... #endif</p>
1071 <p>/* XXX: I think the original author really meant this... */
1072 ...changed code here...</p>
1074 <p>/* XXX: new code that *may* break something else... */ ...new code
1076 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1077 make it clear that this may or may not be a "good thing (tm)", it
1078 will be easier to identify and include in the project (or conversely
1079 exclude from the project).</p>
1083 <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
1084 files and function comment blocks:</a></h2>
1085 <p><span class="emphasis"><i class="EMPHASIS">Example for file
1086 comments:</i></span></p>
1087 <table border="0" bgcolor="#E0E0E0" width="100%">
1090 <pre class="PROGRAMLISTING">
1091 const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$";
1092 /*********************************************************************
1094 * File : $S<!-- Break CVS Substitution -->ource$
1096 * Purpose : (Fill me in with a good description!)
1098 * Copyright : Written by and Copyright (C) 2001-2009
1099 * the Privoxy team. https://www.privoxy.org/
1101 * This program is free software; you can redistribute it
1102 * and/or modify it under the terms of the GNU General
1103 * Public License as published by the Free Software
1104 * Foundation; either version 2 of the License, or (at
1105 * your option) any later version.
1107 * This program is distributed in the hope that it will
1108 * be useful, but WITHOUT ANY WARRANTY; without even the
1109 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1110 * PARTICULAR PURPOSE. See the GNU General Public
1111 * License for more details.
1113 * The GNU General Public License should be included with
1114 * this file. If not, you can view it at
1115 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1116 * or write to the Free Software Foundation, Inc.,
1117 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1120 *********************************************************************/
1125 ...necessary include files for us to do our work...
1127 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;</pre>
1131 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> This
1132 declares the rcs variables that should be added to the
1133 "show-proxy-args" page. If this is a brand new creation by you, you are
1134 free to change the "Copyright" section to represent the rights you wish
1136 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
1137 formfeed character that is present right after the comment flower box
1138 is handy for (X|GNU)Emacs users to skip the verbiage and get to the
1139 heart of the code (via `forward-page' and `backward-page'). Please
1140 include it if you can.</p>
1141 <p><span class="emphasis"><i class="EMPHASIS">Example for file header
1142 comments:</i></span></p>
1143 <table border="0" bgcolor="#E0E0E0" width="100%">
1146 <pre class="PROGRAMLISTING">#ifndef _FILENAME_H
1148 #define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$"
1149 /*********************************************************************
1151 * File : $S<!-- Break CVS Substitution -->ource$
1153 * Purpose : (Fill me in with a good description!)
1155 * Copyright : Written by and Copyright (C) 2001-2009
1156 * the Privoxy team. https://www.privoxy.org/
1158 * This program is free software; you can redistribute it
1159 * and/or modify it under the terms of the GNU General
1160 * Public License as published by the Free Software
1161 * Foundation; either version 2 of the License, or (at
1162 * your option) any later version.
1164 * This program is distributed in the hope that it will
1165 * be useful, but WITHOUT ANY WARRANTY; without even the
1166 * implied warranty of MERCHANTABILITY or FITNESS FOR A
1167 * PARTICULAR PURPOSE. See the GNU General Public
1168 * License for more details.
1170 * The GNU General Public License should be included with
1171 * this file. If not, you can view it at
1172 * http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1173 * or write to the Free Software Foundation, Inc.,
1174 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1177 *********************************************************************/
1180 #include "project.h"
1186 ... function headers here ...
1189 /* Revision control strings from this header and associated .c file */
1190 extern const char FILENAME_rcs[];
1191 extern const char FILENAME_h_rcs[];
1198 #endif /* ndef _FILENAME_H */
1208 <p><span class="emphasis"><i class="EMPHASIS">Example for function
1209 comments:</i></span></p>
1210 <table border="0" bgcolor="#E0E0E0" width="100%">
1213 <pre class="PROGRAMLISTING">
1214 /*********************************************************************
1216 * Function : FUNCTION_NAME
1218 * Description : (Fill me in with a good description!)
1221 * 1 : param1 = pointer to an important thing
1222 * 2 : x = pointer to something else
1224 * Returns : 0 => Ok, everything else is an error.
1226 *********************************************************************/
1227 int FUNCTION_NAME(void *param1, const char *x)
1236 <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If we
1237 all follow this practice, we should be able to parse our code to create
1238 a "self-documenting" web page.</p>
1241 <div class="NAVFOOTER">
1242 <hr align="left" width="100%">
1243 <table summary="Footer navigation table" width="100%" border="0"
1244 cellpadding="0" cellspacing="0">
1246 <td width="33%" align="left" valign="top"><a href=
1247 "documentation.html" accesskey="P">Prev</a></td>
1248 <td width="34%" align="center" valign="top"><a href="index.html"
1249 accesskey="H">Home</a></td>
1250 <td width="33%" align="right" valign="top"><a href="testing.html"
1251 accesskey="N">Next</a></td>
1254 <td width="33%" align="left" valign="top">Documentation
1256 <td width="34%" align="center" valign="top"> </td>
1257 <td width="33%" align="right" valign="top">Testing Guidelines</td>