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
   4 <html>
   5 <head>
   6   <meta name="generator" content=
   7   "HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
   8
   9   <title>Coding Guidelines</title>
  10   <meta name="GENERATOR" content=
  11   "Modular DocBook HTML Stylesheet Version 1.79">
  12   <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
  13   <link rel="PREVIOUS" title="Documentation Guidelines" href=
  14   "documentation.html">
  15   <link rel="NEXT" title="Testing Guidelines" href="testing.html">
  16   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  17   <meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
  18   <style type="text/css">
  19 body {
  20   background-color: #EEEEEE;
  21   color: #000000;
  22   }
  23   :link { color: #0000FF }
  24   :visited { color: #840084 }
  25   :active { color: #0000FF }
  26   table.c3 {background-color: #E0E0E0}
  27   span.c2 {font-style: italic}
  28   hr.c1 {text-align: left}
  29   </style>
  30 </head>
  31
  32 <body class="SECT1">
  33   <div class="NAVHEADER">
  34     <table summary="Header navigation table" width="100%" border="0"
  35     cellpadding="0" cellspacing="0">
  36       <tr>
  37         <th colspan="3" align="center">Privoxy Developer Manual</th>
  38       </tr>
  39
  40       <tr>
  41         <td width="10%" align="left" valign="bottom"><a href=
  42         "documentation.html" accesskey="P">Prev</a></td>
  43
  44         <td width="80%" align="center" valign="bottom"></td>
  45
  46         <td width="10%" align="right" valign="bottom"><a href="testing.html"
  47         accesskey="N">Next</a></td>
  48       </tr>
  49     </table>
  50     <hr class="c1" width="100%">
  51   </div>
  52
  53   <div class="SECT1">
  54     <h1 class="SECT1"><a name="CODING" id="CODING">4. Coding
  55     Guidelines</a></h1>
  56
  57     <div class="SECT2">
  58       <h2 class="SECT2"><a name="S1" id="S1">4.1. Introduction</a></h2>
  59
  60       <p>This set of standards is designed to make our lives easier. It is
  61       developed with the simple goal of helping us keep the "new and improved
  62       <span class="APPLICATION">Privoxy</span>" consistent and reliable. Thus
  63       making maintenance easier and increasing chances of success of the
  64       project.</p>
  65
  66       <p>And that of course comes back to us as individuals. If we can
  67       increase our development and product efficiencies then we can solve
  68       more of the request for changes/improvements and in general feel good
  69       about ourselves. ;-&gt;</p>
  70     </div>
  71
  72     <div class="SECT2">
  73       <h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
  74
  75       <div class="SECT3">
  76         <h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment,
  77         Comment</a></h3>
  78
  79         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
  80
  81         <p>Comment as much as possible without commenting the obvious. For
  82         example do not comment "variable_a is equal to variable_b". Instead
  83         explain why variable_a should be equal to the variable_b. Just
  84         because a person can read code does not mean they will understand why
  85         or what is being done. A reader may spend a lot more time figuring
  86         out what is going on when a simple comment or explanation would have
  87         prevented the extra research. Please help your brother IJB'ers
  88         out!</p>
  89
  90         <p>The comments will also help justify the intent of the code. If the
  91         comment describes something different than what the code is doing
  92         then maybe a programming error is occurring.</p>
  93
  94         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
  95
  96         <table class="c3" border="0" width="100%">
  97           <tr>
  98             <td>
  99               <pre class="PROGRAMLISTING">
 100 /* if page size greater than 1k ... */
 101 if ( page_length() &gt; 1024 )
 102 {
 103     ... "block" the page up ...
 104 }
 105
 106 /* if page size is small, send it in blocks */
 107 if ( page_length() &gt; 1024 )
 108 {
 109     ... "block" the page up ...
 110 }
 111
 112 This demonstrates 2 cases of "what not to do".  The first is a
 113 "syntax comment".  The second is a comment that does not fit what
 114 is actually being done.
 115 </pre>
 116             </td>
 117           </tr>
 118         </table>
 119       </div>
 120
 121       <div class="SECT3">
 122         <h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for
 123         comments</a></h3>
 124
 125         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 126
 127         <p>Comments can help or they can clutter. They help when they are
 128         differentiated from the code they describe. One line comments do not
 129         offer effective separation between the comment and the code. Block
 130         identifiers do, by surrounding the code with a clear, definable
 131         pattern.</p>
 132
 133         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 134
 135         <table class="c3" border="0" width="100%">
 136           <tr>
 137             <td>
 138               <pre class="PROGRAMLISTING">
 139 /*********************************************************************
 140  * This will stand out clearly in your code!
 141  *********************************************************************/
 142 if ( this_variable == that_variable )
 143 {
 144    do_something_very_important();
 145 }
 146
 147
 148 /* unfortunately, this may not */
 149 if ( this_variable == that_variable )
 150 {
 151    do_something_very_important();
 152 }
 153
 154
 155 if ( this_variable == that_variable ) /* this may not either */
 156 {
 157    do_something_very_important();
 158 }
 159 </pre>
 160             </td>
 161           </tr>
 162         </table>
 163
 164         <p><span class="emphasis EMPHASIS c2">Exception:</span></p>
 165
 166         <p>If you are trying to add a small logic comment and do not wish to
 167         "disrupt" the flow of the code, feel free to use a 1 line comment
 168         which is NOT on the same line as the code.</p>
 169       </div>
 170
 171       <div class="SECT3">
 172         <h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their
 173         own line</a></h3>
 174
 175         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 176
 177         <p>It goes back to the question of readability. If the comment is on
 178         the same line as the code it will be harder to read than the comment
 179         that is on its own line.</p>
 180
 181         <p>There are three exceptions to this rule, which should be violated
 182         freely and often: during the definition of variables, at the end of
 183         closing braces, when used to comment parameters.</p>
 184
 185         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 186
 187         <table class="c3" border="0" width="100%">
 188           <tr>
 189             <td>
 190               <pre class="PROGRAMLISTING">
 191 /*********************************************************************
 192  * This will stand out clearly in your code,
 193  * But the second example won't.
 194  *********************************************************************/
 195 if ( this_variable == this_variable )
 196 {
 197    do_something_very_important();
 198 }
 199
 200 if ( this_variable == this_variable ) /*can you see me?*/
 201 {
 202    do_something_very_important(); /*not easily*/
 203 }
 204
 205
 206 /*********************************************************************
 207  * But, the encouraged exceptions:
 208  *********************************************************************/
 209 int urls_read     = 0;     /* # of urls read + rejected */
 210 int urls_rejected = 0;     /* # of urls rejected */
 211
 212 if ( 1 == X )
 213 {
 214    do_something_very_important();
 215 }
 216
 217
 218 short do_something_very_important(
 219    short firstparam,   /* represents something */
 220    short nextparam     /* represents something else */ )
 221 {
 222    ...code here...
 223
 224 }   /* -END- do_something_very_important */
 225 </pre>
 226             </td>
 227           </tr>
 228         </table>
 229       </div>
 230
 231       <div class="SECT3">
 232         <h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical
 233         step</a></h3>
 234
 235         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 236
 237         <p>Logical steps should be commented to help others follow the intent
 238         of the written code and comments will make the code more
 239         readable.</p>
 240
 241         <p>If you have 25 lines of code without a comment, you should
 242         probably go back into it to see where you forgot to put one.</p>
 243
 244         <p>Most "for", "while", "do", etc... loops _probably_ need a comment.
 245         After all, these are usually major logic containers.</p>
 246       </div>
 247
 248       <div class="SECT3">
 249         <h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions
 250         Thoroughly</a></h3>
 251
 252         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 253
 254         <p>A reader of the code should be able to look at the comments just
 255         prior to the beginning of a function and discern the reason for its
 256         existence and the consequences of using it. The reader should not
 257         have to read through the code to determine if a given function is
 258         safe for a desired use. The proper information thoroughly presented
 259         at the introduction of a function not only saves time for subsequent
 260         maintenance or debugging, it more importantly aids in code reuse by
 261         allowing a user to determine the safety and applicability of any
 262         function for the problem at hand. As a result of such benefits, all
 263         functions should contain the information presented in the addendum
 264         section of this document.</p>
 265       </div>
 266
 267       <div class="SECT3">
 268         <h3 class="SECT3"><a name="S8" id="S8">4.2.6. Comment at the end of
 269         braces if the content is more than one screen length</a></h3>
 270
 271         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 272
 273         <p>Each closing brace should be followed on the same line by a
 274         comment that describes the origination of the brace if the original
 275         brace is off of the screen, or otherwise far away from the closing
 276         brace. This will simplify the debugging, maintenance, and readability
 277         of the code.</p>
 278
 279         <p>As a suggestion , use the following flags to make the comment and
 280         its brace more readable:</p>
 281
 282         <p>use following a closing brace: } /* -END- if() or while () or
 283         etc... */</p>
 284
 285         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 286
 287         <table class="c3" border="0" width="100%">
 288           <tr>
 289             <td>
 290               <pre class="PROGRAMLISTING">
 291 if ( 1 == X )
 292 {
 293    do_something_very_important();
 294    ...some long list of commands...
 295 } /* -END- if x is 1 */
 296
 297 or:
 298
 299 if ( 1 == X )
 300 {
 301    do_something_very_important();
 302    ...some long list of commands...
 303 } /* -END- if ( 1 == X ) */
 304 </pre>
 305             </td>
 306           </tr>
 307         </table>
 308       </div>
 309     </div>
 310
 311     <div class="SECT2">
 312       <h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
 313
 314       <div class="SECT3">
 315         <h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable
 316         Names</a></h3>
 317
 318         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 319
 320         <p>Use all lowercase, and separate words via an underscore ('_'). Do
 321         not start an identifier with an underscore. (ANSI C reserves these
 322         for use by the compiler and system headers.) Do not use identifiers
 323         which are reserved in ANSI C++. (E.g. template, class, true, false,
 324         ...). This is in case we ever decide to port Privoxy to C++.</p>
 325
 326         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 327
 328         <table class="c3" border="0" width="100%">
 329           <tr>
 330             <td>
 331               <pre class="PROGRAMLISTING">
 332 int ms_iis5_hack = 0;
 333 </pre>
 334             </td>
 335           </tr>
 336         </table>
 337
 338         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 339
 340         <table class="c3" border="0" width="100%">
 341           <tr>
 342             <td>
 343               <pre class="PROGRAMLISTING">
 344 int msiis5hack = 0; int msIis5Hack = 0;
 345 </pre>
 346             </td>
 347           </tr>
 348         </table>
 349       </div>
 350
 351       <div class="SECT3">
 352         <h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function
 353         Names</a></h3>
 354
 355         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 356
 357         <p>Use all lowercase, and separate words via an underscore ('_'). Do
 358         not start an identifier with an underscore. (ANSI C reserves these
 359         for use by the compiler and system headers.) Do not use identifiers
 360         which are reserved in ANSI C++. (E.g. template, class, true, false,
 361         ...). This is in case we ever decide to port Privoxy to C++.</p>
 362
 363         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 364
 365         <table class="c3" border="0" width="100%">
 366           <tr>
 367             <td>
 368               <pre class="PROGRAMLISTING">
 369 int load_some_file( struct client_state *csp )
 370 </pre>
 371             </td>
 372           </tr>
 373         </table>
 374
 375         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 376
 377         <table class="c3" border="0" width="100%">
 378           <tr>
 379             <td>
 380               <pre class="PROGRAMLISTING">
 381 int loadsomefile( struct client_state *csp )
 382 int loadSomeFile( struct client_state *csp )
 383 </pre>
 384             </td>
 385           </tr>
 386         </table>
 387       </div>
 388
 389       <div class="SECT3">
 390         <h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file
 391         prototypes</a></h3>
 392
 393         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 394
 395         <p>Use a descriptive parameter name in the function prototype in
 396         header files. Use the same parameter name in the header file that you
 397         use in the c file.</p>
 398
 399         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 400
 401         <table class="c3" border="0" width="100%">
 402           <tr>
 403             <td>
 404               <pre class="PROGRAMLISTING">
 405 (.h) extern int load_aclfile( struct client_state *csp );
 406 (.c) int load_aclfile( struct client_state *csp )
 407 </pre>
 408             </td>
 409           </tr>
 410         </table>
 411
 412         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 413
 414         <table class="c3" border="0" width="100%">
 415           <tr>
 416             <td>
 417               <pre class="PROGRAMLISTING">
 418 (.h) extern int load_aclfile( struct client_state * ); or
 419 (.h) extern int load_aclfile();
 420 (.c) int load_aclfile( struct client_state *csp )
 421 </pre>
 422             </td>
 423           </tr>
 424         </table>
 425       </div>
 426
 427       <div class="SECT3">
 428         <h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and
 429         #defines</a></h3>
 430
 431         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 432
 433         <p>Use all capital letters, with underscores between words. Do not
 434         start an identifier with an underscore. (ANSI C reserves these for
 435         use by the compiler and system headers.)</p>
 436
 437         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 438
 439         <table class="c3" border="0" width="100%">
 440           <tr>
 441             <td>
 442               <pre class="PROGRAMLISTING">
 443 (enumeration) : enum Boolean { FALSE, TRUE };
 444 (#define) : #define DEFAULT_SIZE 100;
 445 </pre>
 446             </td>
 447           </tr>
 448         </table>
 449
 450         <p><span class="emphasis EMPHASIS c2">Note:</span> We have a standard
 451         naming scheme for #defines that toggle a feature in the preprocessor:
 452         FEATURE_&gt;, where &gt; is a short (preferably 1 or 2 word)
 453         description.</p>
 454
 455         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 456
 457         <table class="c3" border="0" width="100%">
 458           <tr>
 459             <td>
 460               <pre class="PROGRAMLISTING">
 461 #define FEATURE_FORCE 1
 462
 463 #ifdef FEATURE_FORCE
 464 #define FORCE_PREFIX blah
 465 #endif /* def FEATURE_FORCE */
 466 </pre>
 467             </td>
 468           </tr>
 469         </table>
 470       </div>
 471
 472       <div class="SECT3">
 473         <h3 class="SECT3"><a name="S14" id="S14">4.3.5. Constants</a></h3>
 474
 475         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 476
 477         <p>Spell common words out entirely (do not remove vowels).</p>
 478
 479         <p>Use only widely-known domain acronyms and abbreviations.
 480         Capitalize all letters of an acronym.</p>
 481
 482         <p>Use underscore (_) to separate adjacent acronyms and
 483         abbreviations. Never terminate a name with an underscore.</p>
 484
 485         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 486
 487         <table class="c3" border="0" width="100%">
 488           <tr>
 489             <td>
 490               <pre class="PROGRAMLISTING">
 491 #define USE_IMAGE_LIST 1
 492 </pre>
 493             </td>
 494           </tr>
 495         </table>
 496
 497         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 498
 499         <table class="c3" border="0" width="100%">
 500           <tr>
 501             <td>
 502               <pre class="PROGRAMLISTING">
 503 #define USE_IMG_LST 1 or
 504 #define _USE_IMAGE_LIST 1 or
 505 #define USE_IMAGE_LIST_ 1 or
 506 #define use_image_list 1 or
 507 #define UseImageList 1
 508 </pre>
 509             </td>
 510           </tr>
 511         </table>
 512       </div>
 513     </div>
 514
 515     <div class="SECT2">
 516       <h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
 517
 518       <div class="SECT3">
 519         <h3 class="SECT3"><a name="S16" id="S16">4.4.1. Put braces on a line
 520         by themselves.</a></h3>
 521
 522         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 523
 524         <p>The brace needs to be on a line all by itself, not at the end of
 525         the statement. Curly braces should line up with the construct that
 526         they're associated with. This practice makes it easier to identify
 527         the opening and closing braces for a block.</p>
 528
 529         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 530
 531         <table class="c3" border="0" width="100%">
 532           <tr>
 533             <td>
 534               <pre class="PROGRAMLISTING">
 535 if ( this == that )
 536 {
 537    ...
 538 }
 539 </pre>
 540             </td>
 541           </tr>
 542         </table>
 543
 544         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 545
 546         <p>if ( this == that ) { ... }</p>
 547
 548         <p>or</p>
 549
 550         <p>if ( this == that ) { ... }</p>
 551
 552         <p><span class="emphasis EMPHASIS c2">Note:</span> In the special
 553         case that the if-statement is inside a loop, and it is trivial, i.e.
 554         it tests for a condition that is obvious from the purpose of the
 555         block, one-liners as above may optically preserve the loop structure
 556         and make it easier to read.</p>
 557
 558         <p><span class="emphasis EMPHASIS c2">Status:</span>
 559         developer-discretion.</p>
 560
 561         <p><span class="emphasis EMPHASIS c2">Example exception:</span></p>
 562
 563         <table class="c3" border="0" width="100%">
 564           <tr>
 565             <td>
 566               <pre class="PROGRAMLISTING">
 567 while ( more lines are read )
 568 {
 569    /* Please document what is/is not a comment line here */
 570    if ( it's a comment ) continue;
 571
 572    do_something( line );
 573 }
 574 </pre>
 575             </td>
 576           </tr>
 577         </table>
 578       </div>
 579
 580       <div class="SECT3">
 581         <h3 class="SECT3"><a name="S17" id="S17">4.4.2. ALL control
 582         statements should have a block</a></h3>
 583
 584         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 585
 586         <p>Using braces to make a block will make your code more readable and
 587         less prone to error. All control statements should have a block
 588         defined.</p>
 589
 590         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 591
 592         <table class="c3" border="0" width="100%">
 593           <tr>
 594             <td>
 595               <pre class="PROGRAMLISTING">
 596 if ( this == that )
 597 {
 598    do_something();
 599    do_something_else();
 600 }
 601 </pre>
 602             </td>
 603           </tr>
 604         </table>
 605
 606         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 607
 608         <p>if ( this == that ) do_something(); do_something_else();</p>
 609
 610         <p>or</p>
 611
 612         <p>if ( this == that ) do_something();</p>
 613
 614         <p><span class="emphasis EMPHASIS c2">Note:</span> The first example
 615         in "Instead of" will execute in a manner other than that which the
 616         developer desired (per indentation). Using code braces would have
 617         prevented this "feature". The "explanation" and "exception" from the
 618         point above also applies.</p>
 619       </div>
 620
 621       <div class="SECT3">
 622         <h3 class="SECT3"><a name="S18" id="S18">4.4.3. Do not
 623         belabor/blow-up boolean expressions</a></h3>
 624
 625         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 626
 627         <table class="c3" border="0" width="100%">
 628           <tr>
 629             <td>
 630               <pre class="PROGRAMLISTING">
 631 structure-&gt;flag = ( condition );
 632 </pre>
 633             </td>
 634           </tr>
 635         </table>
 636
 637         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 638
 639         <p>if ( condition ) { structure-&gt;flag = 1; } else {
 640         structure-&gt;flag = 0; }</p>
 641
 642         <p><span class="emphasis EMPHASIS c2">Note:</span> The former is
 643         readable and concise. The later is wordy and inefficient. Please
 644         assume that any developer new to the project has at least a "good"
 645         knowledge of C/C++. (Hope I do not offend by that last comment ...
 646         8-)</p>
 647       </div>
 648
 649       <div class="SECT3">
 650         <h3 class="SECT3"><a name="S19" id="S19">4.4.4. Use white space
 651         freely because it is free</a></h3>
 652
 653         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 654
 655         <p>Make it readable. The notable exception to using white space
 656         freely is listed in the next guideline.</p>
 657
 658         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 659
 660         <table class="c3" border="0" width="100%">
 661           <tr>
 662             <td>
 663               <pre class="PROGRAMLISTING">
 664 int first_value   = 0;
 665 int some_value    = 0;
 666 int another_value = 0;
 667 int this_variable = 0;
 668
 669 if ( this_variable == this_variable )
 670
 671 first_value = old_value + ( ( some_value - another_value ) - whatever )
 672 </pre>
 673             </td>
 674           </tr>
 675         </table>
 676       </div>
 677
 678       <div class="SECT3">
 679         <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
 680         around structure operators</a></h3>
 681
 682         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 683
 684         <p>- structure pointer operator ( "-&gt;" ) - member operator ( "." )
 685         - functions and parentheses</p>
 686
 687         <p>It is a general coding practice to put pointers, references, and
 688         function parentheses next to names. With spaces, the connection
 689         between the object and variable/function name is not as clear.</p>
 690
 691         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 692
 693         <table class="c3" border="0" width="100%">
 694           <tr>
 695             <td>
 696               <pre class="PROGRAMLISTING">
 697 a_struct-&gt;a_member;
 698 a_struct.a_member;
 699 function_name();
 700 </pre>
 701             </td>
 702           </tr>
 703         </table>
 704
 705         <p><span class="emphasis EMPHASIS c2">Instead of:</span> a_struct
 706         -&gt; a_member; a_struct . a_member; function_name ();</p>
 707       </div>
 708
 709       <div class="SECT3">
 710         <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
 711         of a function stand out</a></h3>
 712
 713         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 714
 715         <table class="c3" border="0" width="100%">
 716           <tr>
 717             <td>
 718               <pre class="PROGRAMLISTING">
 719 int function1( ... )
 720 {
 721    ...code...
 722    return( ret_code );
 723
 724 }   /* -END- function1 */
 725
 726
 727 int function2( ... )
 728 {
 729 }   /* -END- function2 */
 730 </pre>
 731             </td>
 732           </tr>
 733         </table>
 734
 735         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
 736
 737         <p>int function1( ... ) { ...code... return( ret_code ); } int
 738         function2( ... ) { }</p>
 739
 740         <p><span class="emphasis EMPHASIS c2">Note:</span> Use 1 blank line
 741         before the closing brace and 2 lines afterward. This makes the end of
 742         function standout to the most casual viewer. Although function
 743         comments help separate functions, this is still a good coding
 744         practice. In fact, I follow these rules when using blocks in "for",
 745         "while", "do" loops, and long if {} statements too. After all
 746         whitespace is free!</p>
 747
 748         <p><span class="emphasis EMPHASIS c2">Status:</span>
 749         developer-discretion on the number of blank lines. Enforced is the
 750         end of function comments.</p>
 751       </div>
 752
 753       <div class="SECT3">
 754         <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
 755         indentions</a></h3>
 756
 757         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 758
 759         <p>If some use 8 character TABs and some use 3 character TABs, the
 760         code can look *very* ragged. So use 3 character indentions only. If
 761         you like to use TABs, pass your code through a filter such as "expand
 762         -t3" before checking in your code.</p>
 763
 764         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 765
 766         <table class="c3" border="0" width="100%">
 767           <tr>
 768             <td>
 769               <pre class="PROGRAMLISTING">
 770 static const char * const url_code_map[256] =
 771 {
 772    NULL, ...
 773 };
 774
 775
 776 int function1( ... )
 777 {
 778    if ( 1 )
 779    {
 780       return( ALWAYS_TRUE );
 781    }
 782    else
 783    {
 784       return( HOW_DID_YOU_GET_HERE );
 785    }
 786
 787    return( NEVER_GETS_HERE );
 788
 789 }
 790 </pre>
 791             </td>
 792           </tr>
 793         </table>
 794       </div>
 795     </div>
 796
 797     <div class="SECT2">
 798       <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
 799
 800       <div class="SECT3">
 801         <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
 802         variables</a></h3>
 803
 804         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 805
 806         <p>Do not assume that the variables declared will not be used until
 807         after they have been assigned a value somewhere else in the code.
 808         Remove the chance of accidentally using an unassigned variable.</p>
 809
 810         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 811
 812         <table class="c3" border="0" width="100%">
 813           <tr>
 814             <td>
 815               <pre class="PROGRAMLISTING">
 816 short a_short = 0;
 817 float a_float  = 0;
 818 struct *ptr = NULL;
 819 </pre>
 820             </td>
 821           </tr>
 822         </table>
 823
 824         <p><span class="emphasis EMPHASIS c2">Note:</span> It is much easier
 825         to debug a SIGSEGV if the message says you are trying to access
 826         memory address 00000000 and not 129FA012; or array_ptr[20] causes a
 827         SIGSEV vs. array_ptr[0].</p>
 828
 829         <p><span class="emphasis EMPHASIS c2">Status:</span>
 830         developer-discretion if and only if the variable is assigned a value
 831         "shortly after" declaration.</p>
 832       </div>
 833     </div>
 834
 835     <div class="SECT2">
 836       <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
 837
 838       <div class="SECT3">
 839         <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
 840         return a boolean as a question.</a></h3>
 841
 842         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 843
 844         <p>Value should be phrased as a question that would logically be
 845         answered as a true or false statement</p>
 846
 847         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 848
 849         <table class="c3" border="0" width="100%">
 850           <tr>
 851             <td>
 852               <pre class="PROGRAMLISTING">
 853 should_we_block_this();
 854 contains_an_image();
 855 is_web_page_blank();
 856 </pre>
 857             </td>
 858           </tr>
 859         </table>
 860       </div>
 861
 862       <div class="SECT3">
 863         <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
 864         return type for a function.</a></h3>
 865
 866         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 867
 868         <p>The default return for a function is an int. To avoid ambiguity,
 869         create a return for a function when the return has a purpose, and
 870         create a void return type if the function does not need to return
 871         anything.</p>
 872       </div>
 873
 874       <div class="SECT3">
 875         <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
 876         calls when iterating by using variables</a></h3>
 877
 878         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 879
 880         <p>It is easy to write the following code, and a clear argument can
 881         be made that the code is easy to understand:</p>
 882
 883         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 884
 885         <table class="c3" border="0" width="100%">
 886           <tr>
 887             <td>
 888               <pre class="PROGRAMLISTING">
 889 for ( size_t cnt = 0; cnt &lt; block_list_length(); cnt++ )
 890 {
 891    ....
 892 }
 893 </pre>
 894             </td>
 895           </tr>
 896         </table>
 897
 898         <p><span class="emphasis EMPHASIS c2">Note:</span> Unfortunately,
 899         this makes a function call for each and every iteration. This
 900         increases the overhead in the program, because the compiler has to
 901         look up the function each time, call it, and return a value.
 902         Depending on what occurs in the block_list_length() call, it might
 903         even be creating and destroying structures with each iteration, even
 904         though in each case it is comparing "cnt" to the same value, over and
 905         over. Remember too - even a call to block_list_length() is a function
 906         call, with the same overhead.</p>
 907
 908         <p>Instead of using a function call during the iterations, assign the
 909         value to a variable, and evaluate using the variable.</p>
 910
 911         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 912
 913         <table class="c3" border="0" width="100%">
 914           <tr>
 915             <td>
 916               <pre class="PROGRAMLISTING">
 917 size_t len = block_list_length();
 918
 919 for ( size_t cnt = 0; cnt &lt; len; cnt++ )
 920 {
 921    ....
 922 }
 923 </pre>
 924             </td>
 925           </tr>
 926         </table>
 927
 928         <p><span class="emphasis EMPHASIS c2">Exceptions:</span> if the value
 929         of block_list_length() *may* change or could *potentially* change,
 930         then you must code the function call in the for/while loop.</p>
 931       </div>
 932
 933       <div class="SECT3">
 934         <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
 935         Const Reference</a></h3>
 936
 937         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 938
 939         <p>This allows a developer to define a const pointer and call your
 940         function. If your function does not have the const keyword, we may
 941         not be able to use your function. Consider strcmp, if it were defined
 942         as: extern int strcmp( char *s1, char *s2 );</p>
 943
 944         <p>I could then not use it to compare argv's in main: int main( int
 945         argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); }</p>
 946
 947         <p>Both these pointers are *const*! If the c runtime library
 948         maintainers do it, we should too.</p>
 949       </div>
 950
 951       <div class="SECT3">
 952         <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
 953         Value</a></h3>
 954
 955         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 956
 957         <p>Most structures cannot fit onto a normal stack entry (i.e. they
 958         are not 4 bytes or less). Aka, a function declaration like: int
 959         load_aclfile( struct client_state csp )</p>
 960
 961         <p>would not work. So, to be consistent, we should declare all
 962         prototypes with "pass by value": int load_aclfile( struct
 963         client_state *csp )</p>
 964       </div>
 965
 966       <div class="SECT3">
 967         <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
 968         files</a></h3>
 969
 970         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
 971
 972         <p>Your include statements should contain the file name without a
 973         path. The path should be listed in the Makefile, using -I as
 974         processor directive to search the indicated paths. An exception to
 975         this would be for some proprietary software that utilizes a partial
 976         path to distinguish their header files from system or other header
 977         files.</p>
 978
 979         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
 980
 981         <table class="c3" border="0" width="100%">
 982           <tr>
 983             <td>
 984               <pre class="PROGRAMLISTING">
 985 #include &lt;iostream.h&gt;     /* This is not a local include */
 986 #include "config.h"       /* This IS a local include */
 987 </pre>
 988             </td>
 989           </tr>
 990         </table>
 991
 992         <p><span class="emphasis EMPHASIS c2">Exception:</span></p>
 993
 994         <table class="c3" border="0" width="100%">
 995           <tr>
 996             <td>
 997               <pre class="PROGRAMLISTING">
 998 /* This is not a local include, but requires a path element. */
 999 #include &lt;sys/fileName.h&gt;
1000 </pre>
1001             </td>
1002           </tr>
1003         </table>
1004
1005         <p><span class="emphasis EMPHASIS c2">Note:</span> Please! do not add
1006         "-I." to the Makefile without a _very_ good reason. This duplicates
1007         the #include "file.h" behavior.</p>
1008       </div>
1009
1010       <div class="SECT3">
1011         <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
1012         inclusion protection</a></h3>
1013
1014         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1015
1016         <p>Prevents compiler and linker errors resulting from redefinition of
1017         items.</p>
1018
1019         <p>Wrap each header file with the following syntax to prevent
1020         multiple inclusions of the file. Of course, replace PROJECT_H with
1021         your file name, with "." Changed to "_", and make it uppercase.</p>
1022
1023         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1024
1025         <table class="c3" border="0" width="100%">
1026           <tr>
1027             <td>
1028               <pre class="PROGRAMLISTING">
1029 #ifndef PROJECT_H_INCLUDED
1030 #define PROJECT_H_INCLUDED
1031  ...
1032 #endif /* ndef PROJECT_H_INCLUDED */
1033 </pre>
1034             </td>
1035           </tr>
1036         </table>
1037       </div>
1038
1039       <div class="SECT3">
1040         <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
1041         appropriate</a></h3>
1042
1043         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1044
1045         <p>If our headers are included from C++, they must declare our
1046         functions as `extern "C"`. This has no cost in C, but increases the
1047         potential re-usability of our code.</p>
1048
1049         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1050
1051         <table class="c3" border="0" width="100%">
1052           <tr>
1053             <td>
1054               <pre class="PROGRAMLISTING">
1055 #ifdef __cplusplus
1056 extern "C"
1057 {
1058 #endif /* def __cplusplus */
1059
1060 ... function definitions here ...
1061
1062 #ifdef __cplusplus
1063 }
1064 #endif /* def __cplusplus */
1065 </pre>
1066             </td>
1067           </tr>
1068         </table>
1069       </div>
1070
1071       <div class="SECT3">
1072         <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
1073         Forward Struct Declaration Instead of Includes</a></h3>
1074
1075         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1076
1077         <p>Useful in headers that include pointers to other struct's.
1078         Modifications to excess header files may cause needless compiles.</p>
1079
1080         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1081
1082         <table class="c3" border="0" width="100%">
1083           <tr>
1084             <td>
1085               <pre class="PROGRAMLISTING">
1086 /*********************************************************************
1087  * We're avoiding an include statement here!
1088  *********************************************************************/
1089 struct file_list;
1090 extern file_list *xyz;
1091 </pre>
1092             </td>
1093           </tr>
1094         </table>
1095
1096         <p><span class="emphasis EMPHASIS c2">Note:</span> If you declare
1097         "file_list xyz;" (without the pointer), then including the proper
1098         header file is necessary. If you only want to prototype a pointer,
1099         however, the header file is unnecessary.</p>
1100
1101         <p><span class="emphasis EMPHASIS c2">Status:</span> Use with
1102         discretion.</p>
1103       </div>
1104     </div>
1105
1106     <div class="SECT2">
1107       <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
1108       Practices</a></h2>
1109
1110       <div class="SECT3">
1111         <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
1112         warnings</a></h3>
1113
1114         <p><span class="emphasis EMPHASIS c2">Explanation</span></p>
1115
1116         <p>Compiler warnings are meant to help you find bugs. You should turn
1117         on as many as possible. With GCC, the switch is "-Wall". Try and fix
1118         as many warnings as possible.</p>
1119       </div>
1120
1121       <div class="SECT3">
1122         <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
1123         case for all switch statements</a></h3>
1124
1125         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1126
1127         <p>What you think is guaranteed is never really guaranteed. The value
1128         that you don't think you need to check is the one that someday will
1129         be passed. So, to protect yourself from the unknown, always have a
1130         default step in a switch statement.</p>
1131
1132         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1133
1134         <table class="c3" border="0" width="100%">
1135           <tr>
1136             <td>
1137               <pre class="PROGRAMLISTING">
1138 switch( hash_string( cmd ) )
1139 {
1140    case hash_actions_file :
1141       ... code ...
1142       break;
1143
1144    case hash_confdir :
1145       ... code ...
1146       break;
1147
1148    default :
1149       log_error( ... );
1150       ... anomaly code goes here ...
1151       continue; / break; / exit( 1 ); / etc ...
1152
1153 } /* end switch( hash_string( cmd ) ) */
1154 </pre>
1155             </td>
1156           </tr>
1157         </table>
1158
1159         <p><span class="emphasis EMPHASIS c2">Note:</span> If you already
1160         have a default condition, you are obviously exempt from this point.
1161         Of note, most of the WIN32 code calls `DefWindowProc' after the
1162         switch statement. This API call *should* be included in a default
1163         statement.</p>
1164
1165         <p><span class="emphasis EMPHASIS c2">Another Note:</span> This is
1166         not so much a readability issue as a robust programming issue. The
1167         "anomaly code goes here" may be no more than a print to the STDERR
1168         stream (as in load_config). Or it may really be an abort
1169         condition.</p>
1170
1171         <p><span class="emphasis EMPHASIS c2">Status:</span> Programmer
1172         discretion is advised.</p>
1173       </div>
1174
1175       <div class="SECT3">
1176         <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
1177         through cases in a switch statement.</a></h3>
1178
1179         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1180
1181         <p>In general, you will want to have a 'break' statement within each
1182         'case' of a switch statement. This allows for the code to be more
1183         readable and understandable, and furthermore can prevent unwanted
1184         surprises if someone else later gets creative and moves the code
1185         around.</p>
1186
1187         <p>The language allows you to plan the fall through from one case
1188         statement to another simply by omitting the break statement within
1189         the case statement. This feature does have benefits, but should only
1190         be used in rare cases. In general, use a break statement for each
1191         case statement.</p>
1192
1193         <p>If you choose to allow fall through, you should comment both the
1194         fact of the fall through and reason why you felt it was
1195         necessary.</p>
1196       </div>
1197
1198       <div class="SECT3">
1199         <h3 class="SECT3"><a name="S39" id="S39">4.7.4. Use 'long' or 'short'
1200         Instead of 'int'</a></h3>
1201
1202         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1203
1204         <p>On 32-bit platforms, int usually has the range of long. On 16-bit
1205         platforms, int has the range of short.</p>
1206
1207         <p><span class="emphasis EMPHASIS c2">Status:</span> open-to-debate.
1208         In the case of most FSF projects (including X/GNU-Emacs), there are
1209         typedefs to int4, int8, int16, (or equivalence ... I forget the exact
1210         typedefs now). Should we add these to IJB now that we have a
1211         "configure" script?</p>
1212       </div>
1213
1214       <div class="SECT3">
1215         <h3 class="SECT3"><a name="S40" id="S40">4.7.5. Don't mix size_t and
1216         other types</a></h3>
1217
1218         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1219
1220         <p>The type of size_t varies across platforms. Do not make
1221         assumptions about whether it is signed or unsigned, or about how long
1222         it is. Do not compare a size_t against another variable of a
1223         different type (or even against a constant) without casting one of
1224         the values.</p>
1225       </div>
1226
1227       <div class="SECT3">
1228         <h3 class="SECT3"><a name="S41" id="S41">4.7.6. Declare each variable
1229         and struct on its own line.</a></h3>
1230
1231         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1232
1233         <p>It can be tempting to declare a series of variables all on one
1234         line. Don't.</p>
1235
1236         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1237
1238         <table class="c3" border="0" width="100%">
1239           <tr>
1240             <td>
1241               <pre class="PROGRAMLISTING">
1242 long a = 0;
1243 long b = 0;
1244 long c = 0;
1245 </pre>
1246             </td>
1247           </tr>
1248         </table>
1249
1250         <p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
1251
1252         <p>long a, b, c;</p>
1253
1254         <p><span class="emphasis EMPHASIS c2">Explanation:</span> - there is
1255         more room for comments on the individual variables - easier to add
1256         new variables without messing up the original ones - when searching
1257         on a variable to find its type, there is less clutter to "visually"
1258         eliminate</p>
1259
1260         <p><span class="emphasis EMPHASIS c2">Exceptions:</span> when you
1261         want to declare a bunch of loop variables or other trivial variables;
1262         feel free to declare them on one line. You should, although, provide
1263         a good comment on their functions.</p>
1264
1265         <p><span class="emphasis EMPHASIS c2">Status:</span>
1266         developer-discretion.</p>
1267       </div>
1268
1269       <div class="SECT3">
1270         <h3 class="SECT3"><a name="S42" id="S42">4.7.7. Use malloc/zalloc
1271         sparingly</a></h3>
1272
1273         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1274
1275         <p>Create a local struct (on the stack) if the variable will live and
1276         die within the context of one function call.</p>
1277
1278         <p>Only "malloc" a struct (on the heap) if the variable's life will
1279         extend beyond the context of one function call.</p>
1280
1281         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1282
1283         <table class="c3" border="0" width="100%">
1284           <tr>
1285             <td>
1286               <pre class="PROGRAMLISTING">
1287 If a function creates a struct and stores a pointer to it in a
1288 list, then it should definitely be allocated via `malloc'.
1289 </pre>
1290             </td>
1291           </tr>
1292         </table>
1293       </div>
1294
1295       <div class="SECT3">
1296         <h3 class="SECT3"><a name="S43" id="S43">4.7.8. The Programmer Who
1297         Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
1298
1299         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1300
1301         <p>If you have to "malloc" an instance, you are responsible for
1302         insuring that the instance is `free'd, even if the deallocation event
1303         falls within some other programmer's code. You are also responsible
1304         for ensuring that deletion is timely (i.e. not too soon, not too
1305         late). This is known as "low-coupling" and is a "good thing (tm)".
1306         You may need to offer a free/unload/destructor type function to
1307         accommodate this.</p>
1308
1309         <p><span class="emphasis EMPHASIS c2">Example:</span></p>
1310
1311         <table class="c3" border="0" width="100%">
1312           <tr>
1313             <td>
1314               <pre class="PROGRAMLISTING">
1315 int load_re_filterfile( struct client_state *csp ) { ... }
1316 static void unload_re_filterfile( void *f ) { ... }
1317 </pre>
1318             </td>
1319           </tr>
1320         </table>
1321
1322         <p><span class="emphasis EMPHASIS c2">Exceptions:</span></p>
1323
1324         <p>The developer cannot be expected to provide `free'ing functions
1325         for C run-time library functions ... such as `strdup'.</p>
1326
1327         <p><span class="emphasis EMPHASIS c2">Status:</span>
1328         developer-discretion. The "main" use of this standard is for
1329         allocating and freeing data structures (complex or nested).</p>
1330       </div>
1331
1332       <div class="SECT3">
1333         <h3 class="SECT3"><a name="S44" id="S44">4.7.9. Add loaders to the
1334         `file_list' structure and in order</a></h3>
1335
1336         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1337
1338         <p>I have ordered all of the "blocker" file code to be in alpha
1339         order. It is easier to add/read new blockers when you expect a
1340         certain order.</p>
1341
1342         <p><span class="emphasis EMPHASIS c2">Note:</span> It may appear that
1343         the alpha order is broken in places by POPUP tests coming before PCRS
1344         tests. But since POPUPs can also be referred to as KILLPOPUPs, it is
1345         clear that it should come first.</p>
1346       </div>
1347
1348       <div class="SECT3">
1349         <h3 class="SECT3"><a name="S45" id="S45">4.7.10. "Uncertain" new code
1350         and/or changes to existing code, use FIXME or XXX</a></h3>
1351
1352         <p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
1353
1354         <p>If you have enough confidence in new code or confidence in your
1355         changes, but are not *quite* sure of the repercussions, add this:</p>
1356
1357         <p>/* FIXME: this code has a logic error on platform XYZ, *
1358         attempting to fix */ #ifdef PLATFORM ...changed code here...
1359         #endif</p>
1360
1361         <p>or:</p>
1362
1363         <p>/* FIXME: I think the original author really meant this... */
1364         ...changed code here...</p>
1365
1366         <p>or:</p>
1367
1368         <p>/* FIXME: new code that *may* break something else... */ ...new
1369         code here...</p>
1370
1371         <p><span class="emphasis EMPHASIS c2">Note:</span> If you make it
1372         clear that this may or may not be a "good thing (tm)", it will be
1373         easier to identify and include in the project (or conversely exclude
1374         from the project).</p>
1375       </div>
1376     </div>
1377
1378     <div class="SECT2">
1379       <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
1380       files and function comment blocks:</a></h2>
1381
1382       <p><span class="emphasis EMPHASIS c2">Example for file
1383       comments:</span></p>
1384
1385       <table class="c3" border="0" width="100%">
1386         <tr>
1387           <td>
1388             <pre class="PROGRAMLISTING">
1389 const char FILENAME_rcs[] = "$Id$";
1390 /*********************************************************************
1391  *
1392  * File        :  $Source$
1393  *
1394  * Purpose     :  (Fill me in with a good description!)
1395  *
1396  * Copyright   :  Written by and Copyright (C) 2001-2009
1397  *                the Privoxy team. http://www.privoxy.org/
1398  *
1399  *                This program is free software; you can redistribute it
1400  *                and/or modify it under the terms of the GNU General
1401  *                Public License as published by the Free Software
1402  *                Foundation; either version 2 of the License, or (at
1403  *                your option) any later version.
1404  *
1405  *                This program is distributed in the hope that it will
1406  *                be useful, but WITHOUT ANY WARRANTY; without even the
1407  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1408  *                PARTICULAR PURPOSE.  See the GNU General Public
1409  *                License for more details.
1410  *
1411  *                The GNU General Public License should be included with
1412  *                this file.  If not, you can view it at
1413  *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1414  *                or write to the Free Software Foundation, Inc.,
1415  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1416  *                USA
1417  *
1418  *********************************************************************/
1419
1420
1421 #include "config.h"
1422
1423    ...necessary include files for us to do our work...
1424
1425 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1426 </pre>
1427           </td>
1428         </tr>
1429       </table>
1430
1431       <p><span class="emphasis EMPHASIS c2">Note:</span> This declares the
1432       rcs variables that should be added to the "show-proxy-args" page. If
1433       this is a brand new creation by you, you are free to change the
1434       "Copyright" section to represent the rights you wish to maintain.</p>
1435
1436       <p><span class="emphasis EMPHASIS c2">Note:</span> The formfeed
1437       character that is present right after the comment flower box is handy
1438       for (X|GNU)Emacs users to skip the verbiage and get to the heart of the
1439       code (via `forward-page' and `backward-page'). Please include it if you
1440       can.</p>
1441
1442       <p><span class="emphasis EMPHASIS c2">Example for file header
1443       comments:</span></p>
1444
1445       <table class="c3" border="0" width="100%">
1446         <tr>
1447           <td>
1448             <pre class="PROGRAMLISTING">
1449 #ifndef _FILENAME_H
1450 #define _FILENAME_H
1451 #define FILENAME_H_VERSION "$Id$"
1452 /*********************************************************************
1453  *
1454  * File        :  $Source$
1455  *
1456  * Purpose     :  (Fill me in with a good description!)
1457  *
1458  * Copyright   :  Written by and Copyright (C) 2001-2009
1459  *                the Privoxy team. http://www.privoxy.org/
1460  *
1461  *                This program is free software; you can redistribute it
1462  *                and/or modify it under the terms of the GNU General
1463  *                Public License as published by the Free Software
1464  *                Foundation; either version 2 of the License, or (at
1465  *                your option) any later version.
1466  *
1467  *                This program is distributed in the hope that it will
1468  *                be useful, but WITHOUT ANY WARRANTY; without even the
1469  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1470  *                PARTICULAR PURPOSE.  See the GNU General Public
1471  *                License for more details.
1472  *
1473  *                The GNU General Public License should be included with
1474  *                this file.  If not, you can view it at
1475  *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1476  *                or write to the Free Software Foundation, Inc.,
1477  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1478  *                USA
1479  *
1480  *********************************************************************/
1481
1482
1483 #include "project.h"
1484
1485 #ifdef __cplusplus
1486 extern "C" {
1487 #endif
1488
1489    ... function headers here ...
1490
1491
1492 /* Revision control strings from this header and associated .c file */
1493 extern const char FILENAME_rcs[];
1494 extern const char FILENAME_h_rcs[];
1495
1496
1497 #ifdef __cplusplus
1498 } /* extern "C" */
1499 #endif
1500
1501 #endif /* ndef _FILENAME_H */
1502
1503 /*
1504   Local Variables:
1505   tab-width: 3
1506   end:
1507 */
1508 </pre>
1509           </td>
1510         </tr>
1511       </table>
1512
1513       <p><span class="emphasis EMPHASIS c2">Example for function
1514       comments:</span></p>
1515
1516       <table class="c3" border="0" width="100%">
1517         <tr>
1518           <td>
1519             <pre class="PROGRAMLISTING">
1520 /*********************************************************************
1521  *
1522  * Function    :  FUNCTION_NAME
1523  *
1524  * Description :  (Fill me in with a good description!)
1525  *
1526  * parameters  :
1527  *          1  :  param1 = pointer to an important thing
1528  *          2  :  x      = pointer to something else
1529  *
1530  * Returns     :  0 =&gt; Ok, everything else is an error.
1531  *
1532  *********************************************************************/
1533 int FUNCTION_NAME( void *param1, const char *x )
1534 {
1535    ...
1536    return( 0 );
1537
1538 }
1539 </pre>
1540           </td>
1541         </tr>
1542       </table>
1543
1544       <p><span class="emphasis EMPHASIS c2">Note:</span> If we all follow
1545       this practice, we should be able to parse our code to create a
1546       "self-documenting" web page.</p>
1547     </div>
1548   </div>
1549
1550   <div class="NAVFOOTER">
1551     <hr class="c1" width="100%">
1552
1553     <table summary="Footer navigation table" width="100%" border="0"
1554     cellpadding="0" cellspacing="0">
1555       <tr>
1556         <td width="33%" align="left" valign="top"><a href=
1557         "documentation.html" accesskey="P">Prev</a></td>
1558
1559         <td width="34%" align="center" valign="top"><a href="index.html"
1560         accesskey="H">Home</a></td>
1561
1562         <td width="33%" align="right" valign="top"><a href="testing.html"
1563         accesskey="N">Next</a></td>
1564       </tr>
1565
1566       <tr>
1567         <td width="33%" align="left" valign="top">Documentation
1568         Guidelines</td>
1569
1570         <td width="34%" align="center" valign="top">&nbsp;</td>
1571
1572         <td width="33%" align="right" valign="top">Testing Guidelines</td>
1573       </tr>
1574     </table>
1575   </div>
1576 </body>
1577 </html>