doc/webserver/developer-manual/coding.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   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=
  10   "documentation.html">
  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">
  14 </head>
  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">
  20       <tr>
  21         <th colspan="3" align="center">Privoxy Developer Manual</th>
  22       </tr>
  23       <tr>
  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>
  29       </tr>
  30     </table>
  31     <hr align="left" width="100%">
  32   </div>
  33   <div class="SECT1">
  34     <h1 class="SECT1"><a name="CODING" id="CODING">4. Coding
  35     Guidelines</a></h1>
  36     <div class="SECT2">
  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
  42       project.</p>
  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. ;-&gt;</p>
  47     </div>
  48     <div class="SECT2">
  49       <h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
  50       <div class="SECT3">
  51         <h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment,
  52         Comment</a></h3>
  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
  62         developers out!</p>
  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%">
  68           <tr>
  69             <td>
  70               <pre class="PROGRAMLISTING">
  71               /* if page size greater than 1k ... */
  72 if (page_length() &gt; 1024)
  73 {
  74     ... "block" the page up ...
  75 }
  76
  77 /* if page size is small, send it in blocks */
  78 if (page_length() &gt; 1024)
  79 {
  80     ... "block" the page up ...
  81 }
  82
  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>
  86             </td>
  87           </tr>
  88         </table>
  89       </div>
  90       <div class="SECT3">
  91         <h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for
  92         comments</a></h3>
  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
  99         pattern.</p>
 100         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 101         <table border="0" bgcolor="#E0E0E0" width="100%">
 102           <tr>
 103             <td>
 104               <pre class="PROGRAMLISTING">
 105               /*********************************************************************
 106  * This will stand out clearly in your code!
 107  *********************************************************************/
 108 if (this_variable == that_variable)
 109 {
 110    do_something_very_important();
 111 }
 112
 113
 114 /* unfortunately, this may not */
 115 if (this_variable == that_variable)
 116 {
 117    do_something_very_important();
 118 }
 119
 120
 121 if (this_variable == that_variable) /* this may not either */
 122 {
 123    do_something_very_important();
 124 }</pre>
 125             </td>
 126           </tr>
 127         </table>
 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>
 133       </div>
 134       <div class="SECT3">
 135         <h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their
 136         own line</a></h3>
 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%">
 147           <tr>
 148             <td>
 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)
 155 {
 156    do_something_very_important();
 157 }
 158
 159 if (this_variable == this_variable) /*can you see me?*/
 160 {
 161    do_something_very_important(); /*not easily*/
 162 }
 163
 164
 165 /*********************************************************************
 166  * But, the encouraged exceptions:
 167  *********************************************************************/
 168 int urls_read     = 0;     /* # of urls read + rejected */
 169 int urls_rejected = 0;     /* # of urls rejected */
 170
 171 if (1 == X)
 172 {
 173    do_something_very_important();
 174 }
 175
 176
 177 short do_something_very_important(
 178    short firstparam,   /* represents something */
 179    short nextparam     /* represents something else */ )
 180 {
 181    ...code here...
 182
 183 }   /* -END- do_something_very_important */</pre>
 184             </td>
 185           </tr>
 186         </table>
 187       </div>
 188       <div class="SECT3">
 189         <h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical
 190         step</a></h3>
 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
 195         readable.</p>
 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>
 200       </div>
 201       <div class="SECT3">
 202         <h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions
 203         Thoroughly</a></h3>
 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>
 217       </div>
 218       <div class="SECT3">
 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
 227         of the code.</p>
 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
 231         etc... */</p>
 232         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 233         <table border="0" bgcolor="#E0E0E0" width="100%">
 234           <tr>
 235             <td>
 236               <pre class="PROGRAMLISTING">if (1 == X)
 237 {
 238    do_something_very_important();
 239    ...some long list of commands...
 240 } /* -END- if x is 1 */
 241
 242 or:
 243
 244 if (1 == X)
 245 {
 246    do_something_very_important();
 247    ...some long list of commands...
 248 } /* -END- if (1 == X) */</pre>
 249             </td>
 250           </tr>
 251         </table>
 252       </div>
 253     </div>
 254     <div class="SECT2">
 255       <h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
 256       <div class="SECT3">
 257         <h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable
 258         Names</a></h3>
 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%">
 268           <tr>
 269             <td>
 270               <pre class="PROGRAMLISTING">int ms_iis5_hack = 0;</pre>
 271             </td>
 272           </tr>
 273         </table>
 274         <p><span class="emphasis"><i class="EMPHASIS">Instead
 275         of:</i></span></p>
 276         <table border="0" bgcolor="#E0E0E0" width="100%">
 277           <tr>
 278             <td>
 279               <pre class="PROGRAMLISTING">
 280               int msiis5hack = 0; int msIis5Hack = 0;</pre>
 281             </td>
 282           </tr>
 283         </table>
 284       </div>
 285       <div class="SECT3">
 286         <h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function
 287         Names</a></h3>
 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%">
 297           <tr>
 298             <td>
 299               <pre class="PROGRAMLISTING">
 300               int load_some_file(struct client_state *csp)</pre>
 301             </td>
 302           </tr>
 303         </table>
 304         <p><span class="emphasis"><i class="EMPHASIS">Instead
 305         of:</i></span></p>
 306         <table border="0" bgcolor="#E0E0E0" width="100%">
 307           <tr>
 308             <td>
 309               <pre class="PROGRAMLISTING">
 310               int loadsomefile(struct client_state *csp)
 311 int loadSomeFile(struct client_state *csp)</pre>
 312             </td>
 313           </tr>
 314         </table>
 315       </div>
 316       <div class="SECT3">
 317         <h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file
 318         prototypes</a></h3>
 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%">
 326           <tr>
 327             <td>
 328               <pre class="PROGRAMLISTING">
 329               (.h) extern int load_aclfile(struct client_state *csp);
 330 (.c) int load_aclfile(struct client_state *csp)</pre>
 331             </td>
 332           </tr>
 333         </table>
 334         <p><span class="emphasis"><i class="EMPHASIS">Instead
 335         of:</i></span></p>
 336         <table border="0" bgcolor="#E0E0E0" width="100%">
 337           <tr>
 338             <td>
 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>
 343             </td>
 344           </tr>
 345         </table>
 346       </div>
 347       <div class="SECT3">
 348         <h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and
 349         #defines</a></h3>
 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%">
 357           <tr>
 358             <td>
 359               <pre class="PROGRAMLISTING">
 360               (enumeration) : enum Boolean {FALSE, TRUE};
 361 (#define) : #define DEFAULT_SIZE 100;</pre>
 362             </td>
 363           </tr>
 364         </table>
 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_&gt;, where &gt; 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%">
 371           <tr>
 372             <td>
 373               <pre class="PROGRAMLISTING">#define FEATURE_FORCE 1
 374
 375 #ifdef FEATURE_FORCE
 376 #define FORCE_PREFIX blah
 377 #endif /* def FEATURE_FORCE */</pre>
 378             </td>
 379           </tr>
 380         </table>
 381       </div>
 382       <div class="SECT3">
 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%">
 393           <tr>
 394             <td>
 395               <pre class="PROGRAMLISTING">#define USE_IMAGE_LIST 1</pre>
 396             </td>
 397           </tr>
 398         </table>
 399         <p><span class="emphasis"><i class="EMPHASIS">Instead
 400         of:</i></span></p>
 401         <table border="0" bgcolor="#E0E0E0" width="100%">
 402           <tr>
 403             <td>
 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>
 409             </td>
 410           </tr>
 411         </table>
 412       </div>
 413     </div>
 414     <div class="SECT2">
 415       <h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
 416       <div class="SECT3">
 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%">
 427           <tr>
 428             <td>
 429               <pre class="PROGRAMLISTING">if (this == that)
 430 {
 431    ...
 432 }</pre>
 433             </td>
 434           </tr>
 435         </table>
 436         <p><span class="emphasis"><i class="EMPHASIS">Instead
 437         of:</i></span></p>
 438         <p>if (this == that) { ... }</p>
 439         <p>or</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%">
 451           <tr>
 452             <td>
 453               <pre class="PROGRAMLISTING">while (more lines are read)
 454 {
 455    /* Please document what is/is not a comment line here */
 456    if (it's a comment) continue;
 457
 458    do_something(line);
 459 }</pre>
 460             </td>
 461           </tr>
 462         </table>
 463       </div>
 464       <div class="SECT3">
 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
 471         defined.</p>
 472         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 473         <table border="0" bgcolor="#E0E0E0" width="100%">
 474           <tr>
 475             <td>
 476               <pre class="PROGRAMLISTING">if (this == that)
 477 {
 478    do_something();
 479    do_something_else();
 480 }</pre>
 481             </td>
 482           </tr>
 483         </table>
 484         <p><span class="emphasis"><i class="EMPHASIS">Instead
 485         of:</i></span></p>
 486         <p>if (this == that) do_something(); do_something_else();</p>
 487         <p>or</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>
 494       </div>
 495       <div class="SECT3">
 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%">
 500           <tr>
 501             <td>
 502               <pre class="PROGRAMLISTING">
 503               structure-&gt;flag = (condition);</pre>
 504             </td>
 505           </tr>
 506         </table>
 507         <p><span class="emphasis"><i class="EMPHASIS">Instead
 508         of:</i></span></p>
 509         <p>if (condition) { structure-&gt;flag = 1; } else {
 510         structure-&gt;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
 515         ... 8-)</p>
 516       </div>
 517       <div class="SECT3">
 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%">
 526           <tr>
 527             <td>
 528               <pre class="PROGRAMLISTING">int first_value   = 0;
 529 int some_value    = 0;
 530 int another_value = 0;
 531 int this_variable = 0;</pre>
 532             </td>
 533           </tr>
 534         </table>
 535       </div>
 536       <div class="SECT3">
 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 ( "-&gt;" ) - 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%">
 548           <tr>
 549             <td>
 550               <pre class="PROGRAMLISTING">a_struct-&gt;a_member;
 551 a_struct.a_member;
 552 function_name();</pre>
 553             </td>
 554           </tr>
 555         </table>
 556         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
 557         a_struct -&gt; a_member; a_struct . a_member; function_name ();</p>
 558       </div>
 559       <div class="SECT3">
 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%">
 564           <tr>
 565             <td>
 566               <pre class="PROGRAMLISTING">int function1( ... )
 567 {
 568    ...code...
 569    return(ret_code);
 570
 571 } /* -END- function1 */
 572
 573
 574 int function2( ... )
 575 {
 576 } /* -END- function2 */</pre>
 577             </td>
 578           </tr>
 579         </table>
 580         <p><span class="emphasis"><i class="EMPHASIS">Instead
 581         of:</i></span></p>
 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>
 594       </div>
 595       <div class="SECT3">
 596         <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
 597         indentions</a></h3>
 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%">
 606           <tr>
 607             <td>
 608               <pre class="PROGRAMLISTING">
 609               static const char * const url_code_map[256] =
 610 {
 611    NULL, ...
 612 };
 613
 614
 615 int function1( ... )
 616 {
 617    if (1)
 618    {
 619       return ALWAYS_TRUE;
 620    }
 621    else
 622    {
 623       return HOW_DID_YOU_GET_HERE;
 624    }
 625
 626    return NEVER_GETS_HERE;
 627
 628 }</pre>
 629             </td>
 630           </tr>
 631         </table>
 632       </div>
 633     </div>
 634     <div class="SECT2">
 635       <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
 636       <div class="SECT3">
 637         <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
 638         variables</a></h3>
 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%">
 646           <tr>
 647             <td>
 648               <pre class="PROGRAMLISTING">short a_short = 0;
 649 float a_float  = 0;
 650 struct *ptr = NULL;</pre>
 651             </td>
 652           </tr>
 653         </table>
 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>
 661       </div>
 662     </div>
 663     <div class="SECT2">
 664       <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
 665       <div class="SECT3">
 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%">
 674           <tr>
 675             <td>
 676               <pre class="PROGRAMLISTING">should_we_block_this();
 677 contains_an_image();
 678 is_web_page_blank();</pre>
 679             </td>
 680           </tr>
 681         </table>
 682       </div>
 683       <div class="SECT3">
 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
 691         anything.</p>
 692       </div>
 693       <div class="SECT3">
 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%">
 702           <tr>
 703             <td>
 704               <pre class="PROGRAMLISTING">
 705               for (size_t cnt = 0; cnt &lt; block_list_length(); cnt++)
 706 {
 707    ....
 708 }</pre>
 709             </td>
 710           </tr>
 711         </table>
 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%">
 725           <tr>
 726             <td>
 727               <pre class="PROGRAMLISTING">size_t len = block_list_length();
 728
 729 for (size_t cnt = 0; cnt &lt; len; cnt++)
 730 {
 731    ....
 732 }</pre>
 733             </td>
 734           </tr>
 735         </table>
 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
 739         for/while loop.</p>
 740       </div>
 741       <div class="SECT3">
 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>
 754       </div>
 755       <div class="SECT3">
 756         <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
 757         Value</a></h3>
 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
 765         *csp)</p>
 766       </div>
 767       <div class="SECT3">
 768         <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
 769         files</a></h3>
 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
 777         files.</p>
 778         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 779         <table border="0" bgcolor="#E0E0E0" width="100%">
 780           <tr>
 781             <td>
 782               <pre class="PROGRAMLISTING">
 783               #include &lt;iostream.h&gt;     /* This is not a local include */
 784 #include "config.h"       /* This IS a local include */</pre>
 785             </td>
 786           </tr>
 787         </table>
 788         <p><span class="emphasis"><i class=
 789         "EMPHASIS">Exception:</i></span></p>
 790         <table border="0" bgcolor="#E0E0E0" width="100%">
 791           <tr>
 792             <td>
 793               <pre class="PROGRAMLISTING">
 794               /* This is not a local include, but requires a path element. */
 795 #include &lt;sys/fileName.h&gt;</pre>
 796             </td>
 797           </tr>
 798         </table>
 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>
 802       </div>
 803       <div class="SECT3">
 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
 809         items.</p>
 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%">
 815           <tr>
 816             <td>
 817               <pre class="PROGRAMLISTING">#ifndef PROJECT_H_INCLUDED
 818 #define PROJECT_H_INCLUDED
 819  ...
 820 #endif /* ndef PROJECT_H_INCLUDED */</pre>
 821             </td>
 822           </tr>
 823         </table>
 824       </div>
 825       <div class="SECT3">
 826         <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
 827         appropriate</a></h3>
 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%">
 835           <tr>
 836             <td>
 837               <pre class="PROGRAMLISTING">#ifdef __cplusplus
 838 extern "C"
 839 {
 840 #endif /* def __cplusplus */
 841
 842 ... function definitions here ...
 843
 844 #ifdef __cplusplus
 845 }
 846 #endif /* def __cplusplus */</pre>
 847             </td>
 848           </tr>
 849         </table>
 850       </div>
 851       <div class="SECT3">
 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%">
 860           <tr>
 861             <td>
 862               <pre class="PROGRAMLISTING">
 863               /*********************************************************************
 864  * We're avoiding an include statement here!
 865  *********************************************************************/
 866 struct file_list;
 867 extern file_list *xyz;</pre>
 868             </td>
 869           </tr>
 870         </table>
 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
 876         with discretion.</p>
 877       </div>
 878     </div>
 879     <div class="SECT2">
 880       <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
 881       Practices</a></h2>
 882       <div class="SECT3">
 883         <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
 884         warnings</a></h3>
 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>
 890       </div>
 891       <div class="SECT3">
 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%">
 902           <tr>
 903             <td>
 904               <pre class="PROGRAMLISTING">switch (hash_string(cmd))
 905 {
 906    case hash_actions_file:
 907       ... code ...
 908       break;
 909
 910    case hash_confdir:
 911       ... code ...
 912       break;
 913
 914    default:
 915       log_error( ... );
 916       ... anomaly code goes here ...
 917       continue; / break; / exit( 1 ); / etc ...
 918
 919 } /* end switch (hash_string(cmd)) */</pre>
 920             </td>
 921           </tr>
 922         </table>
 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
 927         statement.</p>
 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>
 935       </div>
 936       <div class="SECT3">
 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
 945         around.</p>
 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
 950         case statement.</p>
 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
 953         necessary.</p>
 954       </div>
 955       <div class="SECT3">
 956         <h3 class="SECT3"><a name="S40" id="S40">4.7.4. Don't mix size_t and
 957         other types</a></h3>
 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
 964         the values.</p>
 965       </div>
 966       <div class="SECT3">
 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
 972         line. Don't.</p>
 973         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 974         <table border="0" bgcolor="#E0E0E0" width="100%">
 975           <tr>
 976             <td>
 977               <pre class="PROGRAMLISTING">long a = 0;
 978 long b = 0;
 979 long c = 0;</pre>
 980             </td>
 981           </tr>
 982         </table>
 983         <p><span class="emphasis"><i class="EMPHASIS">Instead
 984         of:</i></span></p>
 985         <p>long a, b, c;</p>
 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>
 997       </div>
 998       <div class="SECT3">
 999         <h3 class="SECT3"><a name="S42" id="S42">4.7.6. Use malloc/zalloc
1000         sparingly</a></h3>
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%">
1009           <tr>
1010             <td>
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>
1014             </td>
1015           </tr>
1016         </table>
1017       </div>
1018       <div class="SECT3">
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%">
1032           <tr>
1033             <td>
1034               <pre class="PROGRAMLISTING">
1035               int load_re_filterfile(struct client_state *csp) { ... }
1036 static void unload_re_filterfile(void *f) { ... }</pre>
1037             </td>
1038           </tr>
1039         </table>
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>
1047       </div>
1048       <div class="SECT3">
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
1055         certain order.</p>
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>
1060       </div>
1061       <div class="SECT3">
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>
1070         <p>or:</p>
1071         <p>/* XXX: I think the original author really meant this... */
1072         ...changed code here...</p>
1073         <p>or:</p>
1074         <p>/* XXX: new code that *may* break something else... */ ...new code
1075         here...</p>
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>
1080       </div>
1081     </div>
1082     <div class="SECT2">
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%">
1088         <tr>
1089           <td>
1090             <pre class="PROGRAMLISTING">
1091             const char FILENAME_rcs[] = "$I&lt;!-- Break CVS Substitution --&gt;d$";
1092 /*********************************************************************
1093  *
1094  * File        :  $S&lt;!-- Break CVS Substitution --&gt;ource$
1095  *
1096  * Purpose     :  (Fill me in with a good description!)
1097  *
1098  * Copyright   :  Written by and Copyright (C) 2001-2009
1099  *                the Privoxy team. https://www.privoxy.org/
1100  *
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.
1106  *
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.
1112  *
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 ,
1118  *                USA
1119  *
1120  *********************************************************************/
1121
1122
1123 #include "config.h"
1124
1125    ...necessary include files for us to do our work...
1126
1127 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;</pre>
1128           </td>
1129         </tr>
1130       </table>
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
1135       to maintain.</p>
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%">
1144         <tr>
1145           <td>
1146             <pre class="PROGRAMLISTING">#ifndef _FILENAME_H
1147 #define _FILENAME_H
1148 #define FILENAME_H_VERSION "$I&lt;!-- Break CVS Substitution --&gt;d$"
1149 /*********************************************************************
1150  *
1151  * File        :  $S&lt;!-- Break CVS Substitution --&gt;ource$
1152  *
1153  * Purpose     :  (Fill me in with a good description!)
1154  *
1155  * Copyright   :  Written by and Copyright (C) 2001-2009
1156  *                the Privoxy team. https://www.privoxy.org/
1157  *
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.
1163  *
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.
1169  *
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 ,
1175  *                USA
1176  *
1177  *********************************************************************/
1178
1179
1180 #include "project.h"
1181
1182 #ifdef __cplusplus
1183 extern "C" {
1184 #endif
1185
1186    ... function headers here ...
1187
1188
1189 /* Revision control strings from this header and associated .c file */
1190 extern const char FILENAME_rcs[];
1191 extern const char FILENAME_h_rcs[];
1192
1193
1194 #ifdef __cplusplus
1195 } /* extern "C" */
1196 #endif
1197
1198 #endif /* ndef _FILENAME_H */
1199
1200 /*
1201   Local Variables:
1202   tab-width: 3
1203   end:
1204 */</pre>
1205           </td>
1206         </tr>
1207       </table>
1208       <p><span class="emphasis"><i class="EMPHASIS">Example for function
1209       comments:</i></span></p>
1210       <table border="0" bgcolor="#E0E0E0" width="100%">
1211         <tr>
1212           <td>
1213             <pre class="PROGRAMLISTING">
1214             /*********************************************************************
1215  *
1216  * Function    :  FUNCTION_NAME
1217  *
1218  * Description :  (Fill me in with a good description!)
1219  *
1220  * parameters  :
1221  *          1  :  param1 = pointer to an important thing
1222  *          2  :  x      = pointer to something else
1223  *
1224  * Returns     :  0 =&gt; Ok, everything else is an error.
1225  *
1226  *********************************************************************/
1227 int FUNCTION_NAME(void *param1, const char *x)
1228 {
1229    ...
1230    return 0;
1231
1232 }</pre>
1233           </td>
1234         </tr>
1235       </table>
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>
1239     </div>
1240   </div>
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">
1245       <tr>
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>
1252       </tr>
1253       <tr>
1254         <td width="33%" align="left" valign="top">Documentation
1255         Guidelines</td>
1256         <td width="34%" align="center" valign="top">&nbsp;</td>
1257         <td width="33%" align="right" valign="top">Testing Guidelines</td>
1258       </tr>
1259     </table>
1260   </div>
1261 </body>
1262 </html>