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