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