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 fellow Privoxy
  75         developers 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 </pre>
 678             </td>
 679           </tr>
 680         </table>
 681       </div>
 682
 683       <div class="SECT3">
 684         <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
 685         around structure operators</a></h3>
 686
 687         <p><span class="emphasis"><i class=
 688         "EMPHASIS">Explanation:</i></span></p>
 689
 690         <p>- structure pointer operator ( "-&gt;" ) - member operator ( "." )
 691         - functions and parentheses</p>
 692
 693         <p>It is a general coding practice to put pointers, references, and
 694         function parentheses next to names. With spaces, the connection
 695         between the object and variable/function name is not as clear.</p>
 696
 697         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 698
 699         <table border="0" bgcolor="#E0E0E0" width="100%">
 700           <tr>
 701             <td>
 702               <pre class="PROGRAMLISTING">
 703 a_struct-&gt;a_member;
 704 a_struct.a_member;
 705 function_name();
 706 </pre>
 707             </td>
 708           </tr>
 709         </table>
 710
 711         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span>
 712         a_struct -&gt; a_member; a_struct . a_member; function_name ();</p>
 713       </div>
 714
 715       <div class="SECT3">
 716         <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
 717         of a function stand out</a></h3>
 718
 719         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 720
 721         <table border="0" bgcolor="#E0E0E0" width="100%">
 722           <tr>
 723             <td>
 724               <pre class="PROGRAMLISTING">
 725 int function1( ... )
 726 {
 727    ...code...
 728    return(ret_code);
 729
 730 } /* -END- function1 */
 731
 732
 733 int function2( ... )
 734 {
 735 } /* -END- function2 */
 736 </pre>
 737             </td>
 738           </tr>
 739         </table>
 740
 741         <p><span class="emphasis"><i class="EMPHASIS">Instead
 742         of:</i></span></p>
 743
 744         <p>int function1( ... ) { ...code... return(ret_code); } int
 745         function2( ... ) { }</p>
 746
 747         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> Use 1
 748         blank line before the closing brace and 2 lines afterward. This makes
 749         the end of function standout to the most casual viewer. Although
 750         function comments help separate functions, this is still a good
 751         coding practice. In fact, I follow these rules when using blocks in
 752         "for", "while", "do" loops, and long if {} statements too. After all
 753         whitespace is free!</p>
 754
 755         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
 756         developer-discretion on the number of blank lines. Enforced is the
 757         end of function comments.</p>
 758       </div>
 759
 760       <div class="SECT3">
 761         <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
 762         indentions</a></h3>
 763
 764         <p><span class="emphasis"><i class=
 765         "EMPHASIS">Explanation:</i></span></p>
 766
 767         <p>If some use 8 character TABs and some use 3 character TABs, the
 768         code can look *very* ragged. So use 3 character indentions only. If
 769         you like to use TABs, pass your code through a filter such as "expand
 770         -t3" before checking in your code.</p>
 771
 772         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 773
 774         <table border="0" bgcolor="#E0E0E0" width="100%">
 775           <tr>
 776             <td>
 777               <pre class="PROGRAMLISTING">
 778 static const char * const url_code_map[256] =
 779 {
 780    NULL, ...
 781 };
 782
 783
 784 int function1( ... )
 785 {
 786    if (1)
 787    {
 788       return ALWAYS_TRUE;
 789    }
 790    else
 791    {
 792       return HOW_DID_YOU_GET_HERE;
 793    }
 794
 795    return NEVER_GETS_HERE;
 796
 797 }
 798 </pre>
 799             </td>
 800           </tr>
 801         </table>
 802       </div>
 803     </div>
 804
 805     <div class="SECT2">
 806       <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
 807
 808       <div class="SECT3">
 809         <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
 810         variables</a></h3>
 811
 812         <p><span class="emphasis"><i class=
 813         "EMPHASIS">Explanation:</i></span></p>
 814
 815         <p>Do not assume that the variables declared will not be used until
 816         after they have been assigned a value somewhere else in the code.
 817         Remove the chance of accidentally using an unassigned variable.</p>
 818
 819         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 820
 821         <table border="0" bgcolor="#E0E0E0" width="100%">
 822           <tr>
 823             <td>
 824               <pre class="PROGRAMLISTING">
 825 short a_short = 0;
 826 float a_float  = 0;
 827 struct *ptr = NULL;
 828 </pre>
 829             </td>
 830           </tr>
 831         </table>
 832
 833         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It is
 834         much easier to debug a SIGSEGV if the message says you are trying to
 835         access memory address 00000000 and not 129FA012; or array_ptr[20]
 836         causes a SIGSEV vs. array_ptr[0].</p>
 837
 838         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
 839         developer-discretion if and only if the variable is assigned a value
 840         "shortly after" declaration.</p>
 841       </div>
 842     </div>
 843
 844     <div class="SECT2">
 845       <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
 846
 847       <div class="SECT3">
 848         <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
 849         return a boolean as a question.</a></h3>
 850
 851         <p><span class="emphasis"><i class=
 852         "EMPHASIS">Explanation:</i></span></p>
 853
 854         <p>Value should be phrased as a question that would logically be
 855         answered as a true or false statement</p>
 856
 857         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 858
 859         <table border="0" bgcolor="#E0E0E0" width="100%">
 860           <tr>
 861             <td>
 862               <pre class="PROGRAMLISTING">
 863 should_we_block_this();
 864 contains_an_image();
 865 is_web_page_blank();
 866 </pre>
 867             </td>
 868           </tr>
 869         </table>
 870       </div>
 871
 872       <div class="SECT3">
 873         <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
 874         return type for a function.</a></h3>
 875
 876         <p><span class="emphasis"><i class=
 877         "EMPHASIS">Explanation:</i></span></p>
 878
 879         <p>The default return for a function is an int. To avoid ambiguity,
 880         create a return for a function when the return has a purpose, and
 881         create a void return type if the function does not need to return
 882         anything.</p>
 883       </div>
 884
 885       <div class="SECT3">
 886         <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
 887         calls when iterating by using variables</a></h3>
 888
 889         <p><span class="emphasis"><i class=
 890         "EMPHASIS">Explanation:</i></span></p>
 891
 892         <p>It is easy to write the following code, and a clear argument can
 893         be made that the code is easy to understand:</p>
 894
 895         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 896
 897         <table border="0" bgcolor="#E0E0E0" width="100%">
 898           <tr>
 899             <td>
 900               <pre class="PROGRAMLISTING">
 901 for (size_t cnt = 0; cnt &lt; block_list_length(); cnt++)
 902 {
 903    ....
 904 }
 905 </pre>
 906             </td>
 907           </tr>
 908         </table>
 909
 910         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
 911         Unfortunately, this makes a function call for each and every
 912         iteration. This increases the overhead in the program, because the
 913         compiler has to look up the function each time, call it, and return a
 914         value. Depending on what occurs in the block_list_length() call, it
 915         might even be creating and destroying structures with each iteration,
 916         even though in each case it is comparing "cnt" to the same value,
 917         over and over. Remember too - even a call to block_list_length() is a
 918         function call, with the same overhead.</p>
 919
 920         <p>Instead of using a function call during the iterations, assign the
 921         value to a variable, and evaluate using the variable.</p>
 922
 923         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 924
 925         <table border="0" bgcolor="#E0E0E0" width="100%">
 926           <tr>
 927             <td>
 928               <pre class="PROGRAMLISTING">
 929 size_t len = block_list_length();
 930
 931 for (size_t cnt = 0; cnt &lt; len; cnt++)
 932 {
 933    ....
 934 }
 935 </pre>
 936             </td>
 937           </tr>
 938         </table>
 939
 940         <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
 941         if the value of block_list_length() *may* change or could
 942         *potentially* change, then you must code the function call in the
 943         for/while loop.</p>
 944       </div>
 945
 946       <div class="SECT3">
 947         <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
 948         Const Reference</a></h3>
 949
 950         <p><span class="emphasis"><i class=
 951         "EMPHASIS">Explanation:</i></span></p>
 952
 953         <p>This allows a developer to define a const pointer and call your
 954         function. If your function does not have the const keyword, we may
 955         not be able to use your function. Consider strcmp, if it were defined
 956         as: extern int strcmp(char *s1, char *s2);</p>
 957
 958         <p>I could then not use it to compare argv's in main: int main(int
 959         argc, const char *argv[]) { strcmp(argv[0], "privoxy"); }</p>
 960
 961         <p>Both these pointers are *const*! If the c runtime library
 962         maintainers do it, we should too.</p>
 963       </div>
 964
 965       <div class="SECT3">
 966         <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
 967         Value</a></h3>
 968
 969         <p><span class="emphasis"><i class=
 970         "EMPHASIS">Explanation:</i></span></p>
 971
 972         <p>Most structures cannot fit onto a normal stack entry (i.e. they
 973         are not 4 bytes or less). Aka, a function declaration like: int
 974         load_aclfile(struct client_state csp)</p>
 975
 976         <p>would not work. So, to be consistent, we should declare all
 977         prototypes with "pass by value": int load_aclfile(struct client_state
 978         *csp)</p>
 979       </div>
 980
 981       <div class="SECT3">
 982         <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
 983         files</a></h3>
 984
 985         <p><span class="emphasis"><i class=
 986         "EMPHASIS">Explanation:</i></span></p>
 987
 988         <p>Your include statements should contain the file name without a
 989         path. The path should be listed in the Makefile, using -I as
 990         processor directive to search the indicated paths. An exception to
 991         this would be for some proprietary software that utilizes a partial
 992         path to distinguish their header files from system or other header
 993         files.</p>
 994
 995         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 996
 997         <table border="0" bgcolor="#E0E0E0" width="100%">
 998           <tr>
 999             <td>
1000               <pre class="PROGRAMLISTING">
1001 #include &lt;iostream.h&gt;     /* This is not a local include */
1002 #include "config.h"       /* This IS a local include */
1003 </pre>
1004             </td>
1005           </tr>
1006         </table>
1007
1008         <p><span class="emphasis"><i class=
1009         "EMPHASIS">Exception:</i></span></p>
1010
1011         <table border="0" bgcolor="#E0E0E0" width="100%">
1012           <tr>
1013             <td>
1014               <pre class="PROGRAMLISTING">
1015 /* This is not a local include, but requires a path element. */
1016 #include &lt;sys/fileName.h&gt;
1017 </pre>
1018             </td>
1019           </tr>
1020         </table>
1021
1022         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span>
1023         Please! do not add "-I." to the Makefile without a _very_ good
1024         reason. This duplicates the #include "file.h" behavior.</p>
1025       </div>
1026
1027       <div class="SECT3">
1028         <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
1029         inclusion protection</a></h3>
1030
1031         <p><span class="emphasis"><i class=
1032         "EMPHASIS">Explanation:</i></span></p>
1033
1034         <p>Prevents compiler and linker errors resulting from redefinition of
1035         items.</p>
1036
1037         <p>Wrap each header file with the following syntax to prevent
1038         multiple inclusions of the file. Of course, replace PROJECT_H with
1039         your file name, with "." Changed to "_", and make it uppercase.</p>
1040
1041         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1042
1043         <table border="0" bgcolor="#E0E0E0" width="100%">
1044           <tr>
1045             <td>
1046               <pre class="PROGRAMLISTING">
1047 #ifndef PROJECT_H_INCLUDED
1048 #define PROJECT_H_INCLUDED
1049  ...
1050 #endif /* ndef PROJECT_H_INCLUDED */
1051 </pre>
1052             </td>
1053           </tr>
1054         </table>
1055       </div>
1056
1057       <div class="SECT3">
1058         <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
1059         appropriate</a></h3>
1060
1061         <p><span class="emphasis"><i class=
1062         "EMPHASIS">Explanation:</i></span></p>
1063
1064         <p>If our headers are included from C++, they must declare our
1065         functions as `extern "C"`. This has no cost in C, but increases the
1066         potential re-usability of our code.</p>
1067
1068         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1069
1070         <table border="0" bgcolor="#E0E0E0" width="100%">
1071           <tr>
1072             <td>
1073               <pre class="PROGRAMLISTING">
1074 #ifdef __cplusplus
1075 extern "C"
1076 {
1077 #endif /* def __cplusplus */
1078
1079 ... function definitions here ...
1080
1081 #ifdef __cplusplus
1082 }
1083 #endif /* def __cplusplus */
1084 </pre>
1085             </td>
1086           </tr>
1087         </table>
1088       </div>
1089
1090       <div class="SECT3">
1091         <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
1092         Forward Struct Declaration Instead of Includes</a></h3>
1093
1094         <p><span class="emphasis"><i class=
1095         "EMPHASIS">Explanation:</i></span></p>
1096
1097         <p>Useful in headers that include pointers to other struct's.
1098         Modifications to excess header files may cause needless compiles.</p>
1099
1100         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1101
1102         <table border="0" bgcolor="#E0E0E0" width="100%">
1103           <tr>
1104             <td>
1105               <pre class="PROGRAMLISTING">
1106 /*********************************************************************
1107  * We're avoiding an include statement here!
1108  *********************************************************************/
1109 struct file_list;
1110 extern file_list *xyz;
1111 </pre>
1112             </td>
1113           </tr>
1114         </table>
1115
1116         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1117         declare "file_list xyz;" (without the pointer), then including the
1118         proper header file is necessary. If you only want to prototype a
1119         pointer, however, the header file is unnecessary.</p>
1120
1121         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> Use
1122         with discretion.</p>
1123       </div>
1124     </div>
1125
1126     <div class="SECT2">
1127       <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
1128       Practices</a></h2>
1129
1130       <div class="SECT3">
1131         <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
1132         warnings</a></h3>
1133
1134         <p><span class="emphasis"><i class=
1135         "EMPHASIS">Explanation</i></span></p>
1136
1137         <p>Compiler warnings are meant to help you find bugs. You should turn
1138         on as many as possible. With GCC, the switch is "-Wall". Try and fix
1139         as many warnings as possible.</p>
1140       </div>
1141
1142       <div class="SECT3">
1143         <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
1144         case for all switch statements</a></h3>
1145
1146         <p><span class="emphasis"><i class=
1147         "EMPHASIS">Explanation:</i></span></p>
1148
1149         <p>What you think is guaranteed is never really guaranteed. The value
1150         that you don't think you need to check is the one that someday will
1151         be passed. So, to protect yourself from the unknown, always have a
1152         default step in a switch statement.</p>
1153
1154         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1155
1156         <table border="0" bgcolor="#E0E0E0" width="100%">
1157           <tr>
1158             <td>
1159               <pre class="PROGRAMLISTING">
1160 switch (hash_string(cmd))
1161 {
1162    case hash_actions_file:
1163       ... code ...
1164       break;
1165
1166    case hash_confdir:
1167       ... code ...
1168       break;
1169
1170    default:
1171       log_error( ... );
1172       ... anomaly code goes here ...
1173       continue; / break; / exit( 1 ); / etc ...
1174
1175 } /* end switch (hash_string(cmd)) */
1176 </pre>
1177             </td>
1178           </tr>
1179         </table>
1180
1181         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1182         already have a default condition, you are obviously exempt from this
1183         point. Of note, most of the WIN32 code calls `DefWindowProc' after
1184         the switch statement. This API call *should* be included in a default
1185         statement.</p>
1186
1187         <p><span class="emphasis"><i class="EMPHASIS">Another
1188         Note:</i></span> This is not so much a readability issue as a robust
1189         programming issue. The "anomaly code goes here" may be no more than a
1190         print to the STDERR stream (as in load_config). Or it may really be
1191         an abort condition.</p>
1192
1193         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1194         Programmer discretion is advised.</p>
1195       </div>
1196
1197       <div class="SECT3">
1198         <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
1199         through cases in a switch statement.</a></h3>
1200
1201         <p><span class="emphasis"><i class=
1202         "EMPHASIS">Explanation:</i></span></p>
1203
1204         <p>In general, you will want to have a 'break' statement within each
1205         'case' of a switch statement. This allows for the code to be more
1206         readable and understandable, and furthermore can prevent unwanted
1207         surprises if someone else later gets creative and moves the code
1208         around.</p>
1209
1210         <p>The language allows you to plan the fall through from one case
1211         statement to another simply by omitting the break statement within
1212         the case statement. This feature does have benefits, but should only
1213         be used in rare cases. In general, use a break statement for each
1214         case statement.</p>
1215
1216         <p>If you choose to allow fall through, you should comment both the
1217         fact of the fall through and reason why you felt it was
1218         necessary.</p>
1219       </div>
1220
1221       <div class="SECT3">
1222         <h3 class="SECT3"><a name="S40" id="S40">4.7.4. Don't mix size_t and
1223         other types</a></h3>
1224
1225         <p><span class="emphasis"><i class=
1226         "EMPHASIS">Explanation:</i></span></p>
1227
1228         <p>The type of size_t varies across platforms. Do not make
1229         assumptions about whether it is signed or unsigned, or about how long
1230         it is. Do not compare a size_t against another variable of a
1231         different type (or even against a constant) without casting one of
1232         the values.</p>
1233       </div>
1234
1235       <div class="SECT3">
1236         <h3 class="SECT3"><a name="S41" id="S41">4.7.5. Declare each variable
1237         and struct on its own line.</a></h3>
1238
1239         <p><span class="emphasis"><i class=
1240         "EMPHASIS">Explanation:</i></span></p>
1241
1242         <p>It can be tempting to declare a series of variables all on one
1243         line. Don't.</p>
1244
1245         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1246
1247         <table border="0" bgcolor="#E0E0E0" width="100%">
1248           <tr>
1249             <td>
1250               <pre class="PROGRAMLISTING">
1251 long a = 0;
1252 long b = 0;
1253 long c = 0;
1254 </pre>
1255             </td>
1256           </tr>
1257         </table>
1258
1259         <p><span class="emphasis"><i class="EMPHASIS">Instead
1260         of:</i></span></p>
1261
1262         <p>long a, b, c;</p>
1263
1264         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span>
1265         - there is more room for comments on the individual variables -
1266         easier to add new variables without messing up the original ones -
1267         when searching on a variable to find its type, there is less clutter
1268         to "visually" eliminate</p>
1269
1270         <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span>
1271         when you want to declare a bunch of loop variables or other trivial
1272         variables; feel free to declare them on one line. You should,
1273         although, provide a good comment on their functions.</p>
1274
1275         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1276         developer-discretion.</p>
1277       </div>
1278
1279       <div class="SECT3">
1280         <h3 class="SECT3"><a name="S42" id="S42">4.7.6. Use malloc/zalloc
1281         sparingly</a></h3>
1282
1283         <p><span class="emphasis"><i class=
1284         "EMPHASIS">Explanation:</i></span></p>
1285
1286         <p>Create a local struct (on the stack) if the variable will live and
1287         die within the context of one function call.</p>
1288
1289         <p>Only "malloc" a struct (on the heap) if the variable's life will
1290         extend beyond the context of one function call.</p>
1291
1292         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1293
1294         <table border="0" bgcolor="#E0E0E0" width="100%">
1295           <tr>
1296             <td>
1297               <pre class="PROGRAMLISTING">
1298 If a function creates a struct and stores a pointer to it in a
1299 list, then it should definitely be allocated via `malloc'.
1300 </pre>
1301             </td>
1302           </tr>
1303         </table>
1304       </div>
1305
1306       <div class="SECT3">
1307         <h3 class="SECT3"><a name="S43" id="S43">4.7.7. The Programmer Who
1308         Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
1309
1310         <p><span class="emphasis"><i class=
1311         "EMPHASIS">Explanation:</i></span></p>
1312
1313         <p>If you have to "malloc" an instance, you are responsible for
1314         insuring that the instance is `free'd, even if the deallocation event
1315         falls within some other programmer's code. You are also responsible
1316         for ensuring that deletion is timely (i.e. not too soon, not too
1317         late). This is known as "low-coupling" and is a "good thing (tm)".
1318         You may need to offer a free/unload/destructor type function to
1319         accommodate this.</p>
1320
1321         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
1322
1323         <table border="0" bgcolor="#E0E0E0" width="100%">
1324           <tr>
1325             <td>
1326               <pre class="PROGRAMLISTING">
1327 int load_re_filterfile(struct client_state *csp) { ... }
1328 static void unload_re_filterfile(void *f) { ... }
1329 </pre>
1330             </td>
1331           </tr>
1332         </table>
1333
1334         <p><span class="emphasis"><i class=
1335         "EMPHASIS">Exceptions:</i></span></p>
1336
1337         <p>The developer cannot be expected to provide `free'ing functions
1338         for C run-time library functions ... such as `strdup'.</p>
1339
1340         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span>
1341         developer-discretion. The "main" use of this standard is for
1342         allocating and freeing data structures (complex or nested).</p>
1343       </div>
1344
1345       <div class="SECT3">
1346         <h3 class="SECT3"><a name="S44" id="S44">4.7.8. Add loaders to the
1347         `file_list' structure and in order</a></h3>
1348
1349         <p><span class="emphasis"><i class=
1350         "EMPHASIS">Explanation:</i></span></p>
1351
1352         <p>I have ordered all of the "blocker" file code to be in alpha
1353         order. It is easier to add/read new blockers when you expect a
1354         certain order.</p>
1355
1356         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It may
1357         appear that the alpha order is broken in places by POPUP tests coming
1358         before PCRS tests. But since POPUPs can also be referred to as
1359         KILLPOPUPs, it is clear that it should come first.</p>
1360       </div>
1361
1362       <div class="SECT3">
1363         <h3 class="SECT3"><a name="S45" id="S45">4.7.9. "Uncertain" new code
1364         and/or changes to existing code, use XXX</a></h3>
1365
1366         <p><span class="emphasis"><i class=
1367         "EMPHASIS">Explanation:</i></span></p>
1368
1369         <p>If you have enough confidence in new code or confidence in your
1370         changes, but are not *quite* sure of the repercussions, add this:</p>
1371
1372         <p>/* XXX: this code has a logic error on platform XYZ, * attempting
1373         to fix */ #ifdef PLATFORM ...changed code here... #endif</p>
1374
1375         <p>or:</p>
1376
1377         <p>/* XXX: I think the original author really meant this... */
1378         ...changed code here...</p>
1379
1380         <p>or:</p>
1381
1382         <p>/* XXX: new code that *may* break something else... */ ...new code
1383         here...</p>
1384
1385         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you
1386         make it clear that this may or may not be a "good thing (tm)", it
1387         will be easier to identify and include in the project (or conversely
1388         exclude from the project).</p>
1389       </div>
1390     </div>
1391
1392     <div class="SECT2">
1393       <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
1394       files and function comment blocks:</a></h2>
1395
1396       <p><span class="emphasis"><i class="EMPHASIS">Example for file
1397       comments:</i></span></p>
1398
1399       <table border="0" bgcolor="#E0E0E0" width="100%">
1400         <tr>
1401           <td>
1402             <pre class="PROGRAMLISTING">
1403 const char FILENAME_rcs[] = "$I&lt;!-- Break CVS Substitution --&gt;d$";
1404 /*********************************************************************
1405  *
1406  * File        :  $S&lt;!-- Break CVS Substitution --&gt;ource$
1407  *
1408  * Purpose     :  (Fill me in with a good description!)
1409  *
1410  * Copyright   :  Written by and Copyright (C) 2001-2009
1411  *                the Privoxy team. http://www.privoxy.org/
1412  *
1413  *                This program is free software; you can redistribute it
1414  *                and/or modify it under the terms of the GNU General
1415  *                Public License as published by the Free Software
1416  *                Foundation; either version 2 of the License, or (at
1417  *                your option) any later version.
1418  *
1419  *                This program is distributed in the hope that it will
1420  *                be useful, but WITHOUT ANY WARRANTY; without even the
1421  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1422  *                PARTICULAR PURPOSE.  See the GNU General Public
1423  *                License for more details.
1424  *
1425  *                The GNU General Public License should be included with
1426  *                this file.  If not, you can view it at
1427  *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1428  *                or write to the Free Software Foundation, Inc.,
1429  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1430  *                USA
1431  *
1432  *********************************************************************/
1433
1434
1435 #include "config.h"
1436
1437    ...necessary include files for us to do our work...
1438
1439 const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
1440 </pre>
1441           </td>
1442         </tr>
1443       </table>
1444
1445       <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> This
1446       declares the rcs variables that should be added to the
1447       "show-proxy-args" page. If this is a brand new creation by you, you are
1448       free to change the "Copyright" section to represent the rights you wish
1449       to maintain.</p>
1450
1451       <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The
1452       formfeed character that is present right after the comment flower box
1453       is handy for (X|GNU)Emacs users to skip the verbiage and get to the
1454       heart of the code (via `forward-page' and `backward-page'). Please
1455       include it if you can.</p>
1456
1457       <p><span class="emphasis"><i class="EMPHASIS">Example for file header
1458       comments:</i></span></p>
1459
1460       <table border="0" bgcolor="#E0E0E0" width="100%">
1461         <tr>
1462           <td>
1463             <pre class="PROGRAMLISTING">
1464 #ifndef _FILENAME_H
1465 #define _FILENAME_H
1466 #define FILENAME_H_VERSION "$I&lt;!-- Break CVS Substitution --&gt;d$"
1467 /*********************************************************************
1468  *
1469  * File        :  $S&lt;!-- Break CVS Substitution --&gt;ource$
1470  *
1471  * Purpose     :  (Fill me in with a good description!)
1472  *
1473  * Copyright   :  Written by and Copyright (C) 2001-2009
1474  *                the Privoxy team. http://www.privoxy.org/
1475  *
1476  *                This program is free software; you can redistribute it
1477  *                and/or modify it under the terms of the GNU General
1478  *                Public License as published by the Free Software
1479  *                Foundation; either version 2 of the License, or (at
1480  *                your option) any later version.
1481  *
1482  *                This program is distributed in the hope that it will
1483  *                be useful, but WITHOUT ANY WARRANTY; without even the
1484  *                implied warranty of MERCHANTABILITY or FITNESS FOR A
1485  *                PARTICULAR PURPOSE.  See the GNU General Public
1486  *                License for more details.
1487  *
1488  *                The GNU General Public License should be included with
1489  *                this file.  If not, you can view it at
1490  *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
1491  *                or write to the Free Software Foundation, Inc.,
1492  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
1493  *                USA
1494  *
1495  *********************************************************************/
1496
1497
1498 #include "project.h"
1499
1500 #ifdef __cplusplus
1501 extern "C" {
1502 #endif
1503
1504    ... function headers here ...
1505
1506
1507 /* Revision control strings from this header and associated .c file */
1508 extern const char FILENAME_rcs[];
1509 extern const char FILENAME_h_rcs[];
1510
1511
1512 #ifdef __cplusplus
1513 } /* extern "C" */
1514 #endif
1515
1516 #endif /* ndef _FILENAME_H */
1517
1518 /*
1519   Local Variables:
1520   tab-width: 3
1521   end:
1522 */
1523 </pre>
1524           </td>
1525         </tr>
1526       </table>
1527
1528       <p><span class="emphasis"><i class="EMPHASIS">Example for function
1529       comments:</i></span></p>
1530
1531       <table border="0" bgcolor="#E0E0E0" width="100%">
1532         <tr>
1533           <td>
1534             <pre class="PROGRAMLISTING">
1535 /*********************************************************************
1536  *
1537  * Function    :  FUNCTION_NAME
1538  *
1539  * Description :  (Fill me in with a good description!)
1540  *
1541  * parameters  :
1542  *          1  :  param1 = pointer to an important thing
1543  *          2  :  x      = pointer to something else
1544  *
1545  * Returns     :  0 =&gt; Ok, everything else is an error.
1546  *
1547  *********************************************************************/
1548 int FUNCTION_NAME(void *param1, const char *x)
1549 {
1550    ...
1551    return 0;
1552
1553 }
1554 </pre>
1555           </td>
1556         </tr>
1557       </table>
1558
1559       <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If we
1560       all follow this practice, we should be able to parse our code to create
1561       a "self-documenting" web page.</p>
1562     </div>
1563   </div>
1564
1565   <div class="NAVFOOTER">
1566     <hr align="left" width="100%">
1567
1568     <table summary="Footer navigation table" width="100%" border="0"
1569     cellpadding="0" cellspacing="0">
1570       <tr>
1571         <td width="33%" align="left" valign="top"><a href=
1572         "documentation.html" accesskey="P">Prev</a></td>
1573
1574         <td width="34%" align="center" valign="top"><a href="index.html"
1575         accesskey="H">Home</a></td>
1576
1577         <td width="33%" align="right" valign="top"><a href="testing.html"
1578         accesskey="N">Next</a></td>
1579       </tr>
1580
1581       <tr>
1582         <td width="33%" align="left" valign="top">Documentation
1583         Guidelines</td>
1584
1585         <td width="34%" align="center" valign="top">&nbsp;</td>
1586
1587         <td width="33%" align="right" valign="top">Testing Guidelines</td>
1588       </tr>
1589     </table>
1590   </div>
1591 </body>
1592 </html>