doc/webserver/developer-manual/coding.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
   2 "http://www.w3.org/TR/html4/loose.dtd">
   3 <html>
   4 <head>
   5   <title>Coding Guidelines</title>
   6   <meta name="GENERATOR" content="Modular DocBook HTML Stylesheet Version 1.79">
   7   <link rel="HOME" title="Privoxy Developer Manual" href="index.html">
   8   <link rel="PREVIOUS" title="Documentation Guidelines" href="documentation.html">
   9   <link rel="NEXT" title="Testing Guidelines" href="testing.html">
  10   <link rel="STYLESHEET" type="text/css" href="../p_doc.css">
  11   <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
  12 </head>
  13 <body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink="#840084" alink="#0000FF">
  14   <div class="NAVHEADER">
  15     <table summary="Header navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
  16       <tr>
  17         <th colspan="3" align="center">Privoxy Developer Manual</th>
  18       </tr>
  19       <tr>
  20         <td width="10%" align="left" valign="bottom"><a href="documentation.html" accesskey="P">Prev</a></td>
  21         <td width="80%" align="center" valign="bottom"></td>
  22         <td width="10%" align="right" valign="bottom"><a href="testing.html" accesskey="N">Next</a></td>
  23       </tr>
  24     </table>
  25     <hr align="left" width="100%">
  26   </div>
  27   <div class="SECT1">
  28     <h1 class="SECT1"><a name="CODING" id="CODING">4. Coding Guidelines</a></h1>
  29     <div class="SECT2">
  30       <h2 class="SECT2"><a name="S1" id="S1">4.1. Introduction</a></h2>
  31       <p>This set of standards is designed to make our lives easier. It is developed with the simple goal of helping us
  32       keep the "new and improved <span class="APPLICATION">Privoxy</span>" consistent and reliable. Thus making
  33       maintenance easier and increasing chances of success of the project.</p>
  34       <p>And that of course comes back to us as individuals. If we can increase our development and product
  35       efficiencies then we can solve more of the request for changes/improvements and in general feel good about
  36       ourselves. ;-&#62;</p>
  37     </div>
  38     <div class="SECT2">
  39       <h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
  40       <div class="SECT3">
  41         <h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment, Comment</a></h3>
  42         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
  43         <p>Comment as much as possible without commenting the obvious. For example do not comment "variable_a is equal
  44         to variable_b". Instead explain why variable_a should be equal to the variable_b. Just because a person can
  45         read code does not mean they will understand why or what is being done. A reader may spend a lot more time
  46         figuring out what is going on when a simple comment or explanation would have prevented the extra research.
  47         Please help your fellow Privoxy developers out!</p>
  48         <p>The comments will also help justify the intent of the code. If the comment describes something different
  49         than what the code is doing then maybe a programming error is occurring.</p>
  50         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
  51         <table border="0" bgcolor="#E0E0E0" width="100%">
  52           <tr>
  53             <td>
  54               <pre class="PROGRAMLISTING">  /* if page size greater than 1k ... */
  55   if (page_length() &#62; 1024)
  56   {
  57       ... "block" the page up ...
  58   }
  59
  60   /* if page size is small, send it in blocks */
  61   if (page_length() &#62; 1024)
  62   {
  63       ... "block" the page up ...
  64   }
  65
  66   This demonstrates 2 cases of "what not to do".  The first is a
  67   "syntax comment".  The second is a comment that does not fit what
  68   is actually being done.</pre>
  69             </td>
  70           </tr>
  71         </table>
  72       </div>
  73       <div class="SECT3">
  74         <h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for comments</a></h3>
  75         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
  76         <p>Comments can help or they can clutter. They help when they are differentiated from the code they describe.
  77         One line comments do not offer effective separation between the comment and the code. Block identifiers do, by
  78         surrounding the code with a clear, definable pattern.</p>
  79         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
  80         <table border="0" bgcolor="#E0E0E0" width="100%">
  81           <tr>
  82             <td>
  83               <pre class="PROGRAMLISTING">  /*********************************************************************
  84    * This will stand out clearly in your code!
  85    *********************************************************************/
  86   if (this_variable == that_variable)
  87   {
  88      do_something_very_important();
  89   }
  90
  91
  92   /* unfortunately, this may not */
  93   if (this_variable == that_variable)
  94   {
  95      do_something_very_important();
  96   }
  97
  98
  99   if (this_variable == that_variable) /* this may not either */
 100   {
 101      do_something_very_important();
 102   }</pre>
 103             </td>
 104           </tr>
 105         </table>
 106         <p><span class="emphasis"><i class="EMPHASIS">Exception:</i></span></p>
 107         <p>If you are trying to add a small logic comment and do not wish to "disrupt" the flow of the code, feel free
 108         to use a 1 line comment which is NOT on the same line as the code.</p>
 109       </div>
 110       <div class="SECT3">
 111         <h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their own line</a></h3>
 112         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 113         <p>It goes back to the question of readability. If the comment is on the same line as the code it will be
 114         harder to read than the comment that is on its own line.</p>
 115         <p>There are three exceptions to this rule, which should be violated freely and often: during the definition of
 116         variables, at the end of closing braces, when used to comment parameters.</p>
 117         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 118         <table border="0" bgcolor="#E0E0E0" width="100%">
 119           <tr>
 120             <td>
 121               <pre class="PROGRAMLISTING">  /*********************************************************************
 122    * This will stand out clearly in your code,
 123    * But the second example won't.
 124    *********************************************************************/
 125   if (this_variable == this_variable)
 126   {
 127      do_something_very_important();
 128   }
 129
 130   if (this_variable == this_variable) /*can you see me?*/
 131   {
 132      do_something_very_important(); /*not easily*/
 133   }
 134
 135
 136   /*********************************************************************
 137    * But, the encouraged exceptions:
 138    *********************************************************************/
 139   int urls_read     = 0;     /* # of urls read + rejected */
 140   int urls_rejected = 0;     /* # of urls rejected */
 141
 142   if (1 == X)
 143   {
 144      do_something_very_important();
 145   }
 146
 147
 148   short do_something_very_important(
 149      short firstparam,   /* represents something */
 150      short nextparam     /* represents something else */ )
 151   {
 152      ...code here...
 153
 154   }   /* -END- do_something_very_important */</pre>
 155             </td>
 156           </tr>
 157         </table>
 158       </div>
 159       <div class="SECT3">
 160         <h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical step</a></h3>
 161         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 162         <p>Logical steps should be commented to help others follow the intent of the written code and comments will
 163         make the code more readable.</p>
 164         <p>If you have 25 lines of code without a comment, you should probably go back into it to see where you forgot
 165         to put one.</p>
 166         <p>Most "for", "while", "do", etc... loops _probably_ need a comment. After all, these are usually major logic
 167         containers.</p>
 168       </div>
 169       <div class="SECT3">
 170         <h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions Thoroughly</a></h3>
 171         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 172         <p>A reader of the code should be able to look at the comments just prior to the beginning of a function and
 173         discern the reason for its existence and the consequences of using it. The reader should not have to read
 174         through the code to determine if a given function is safe for a desired use. The proper information thoroughly
 175         presented at the introduction of a function not only saves time for subsequent maintenance or debugging, it
 176         more importantly aids in code reuse by allowing a user to determine the safety and applicability of any
 177         function for the problem at hand. As a result of such benefits, all functions should contain the information
 178         presented in the addendum section of this document.</p>
 179       </div>
 180       <div class="SECT3">
 181         <h3 class="SECT3"><a name="S8" id="S8">4.2.6. Comment at the end of braces if the content is more than one
 182         screen length</a></h3>
 183         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 184         <p>Each closing brace should be followed on the same line by a comment that describes the origination of the
 185         brace if the original brace is off of the screen, or otherwise far away from the closing brace. This will
 186         simplify the debugging, maintenance, and readability of the code.</p>
 187         <p>As a suggestion , use the following flags to make the comment and its brace more readable:</p>
 188         <p>use following a closing brace: } /* -END- if() or while () or etc... */</p>
 189         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 190         <table border="0" bgcolor="#E0E0E0" width="100%">
 191           <tr>
 192             <td>
 193               <pre class="PROGRAMLISTING">  if (1 == X)
 194   {
 195      do_something_very_important();
 196      ...some long list of commands...
 197   } /* -END- if x is 1 */
 198
 199   or:
 200
 201   if (1 == X)
 202   {
 203      do_something_very_important();
 204      ...some long list of commands...
 205   } /* -END- if (1 == X) */</pre>
 206             </td>
 207           </tr>
 208         </table>
 209       </div>
 210     </div>
 211     <div class="SECT2">
 212       <h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
 213       <div class="SECT3">
 214         <h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable Names</a></h3>
 215         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 216         <p>Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an
 217         underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which
 218         are reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in case we ever decide to port
 219         Privoxy to C++.</p>
 220         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 221         <table border="0" bgcolor="#E0E0E0" width="100%">
 222           <tr>
 223             <td>
 224               <pre class="PROGRAMLISTING">  int ms_iis5_hack = 0;</pre>
 225             </td>
 226           </tr>
 227         </table>
 228         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 229         <table border="0" bgcolor="#E0E0E0" width="100%">
 230           <tr>
 231             <td>
 232               <pre class="PROGRAMLISTING">  int msiis5hack = 0; int msIis5Hack = 0;</pre>
 233             </td>
 234           </tr>
 235         </table>
 236       </div>
 237       <div class="SECT3">
 238         <h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function Names</a></h3>
 239         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 240         <p>Use all lowercase, and separate words via an underscore ('_'). Do not start an identifier with an
 241         underscore. (ANSI C reserves these for use by the compiler and system headers.) Do not use identifiers which
 242         are reserved in ANSI C++. (E.g. template, class, true, false, ...). This is in case we ever decide to port
 243         Privoxy to C++.</p>
 244         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 245         <table border="0" bgcolor="#E0E0E0" width="100%">
 246           <tr>
 247             <td>
 248               <pre class="PROGRAMLISTING">  int load_some_file(struct client_state *csp)</pre>
 249             </td>
 250           </tr>
 251         </table>
 252         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 253         <table border="0" bgcolor="#E0E0E0" width="100%">
 254           <tr>
 255             <td>
 256               <pre class="PROGRAMLISTING">  int loadsomefile(struct client_state *csp)
 257   int loadSomeFile(struct client_state *csp)</pre>
 258             </td>
 259           </tr>
 260         </table>
 261       </div>
 262       <div class="SECT3">
 263         <h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file prototypes</a></h3>
 264         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 265         <p>Use a descriptive parameter name in the function prototype in header files. Use the same parameter name in
 266         the header file that you use in the c file.</p>
 267         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 268         <table border="0" bgcolor="#E0E0E0" width="100%">
 269           <tr>
 270             <td>
 271               <pre class="PROGRAMLISTING">  (.h) extern int load_aclfile(struct client_state *csp);
 272   (.c) int load_aclfile(struct client_state *csp)</pre>
 273             </td>
 274           </tr>
 275         </table>
 276         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 277         <table border="0" bgcolor="#E0E0E0" width="100%">
 278           <tr>
 279             <td>
 280               <pre class="PROGRAMLISTING">  (.h) extern int load_aclfile(struct client_state *); or
 281   (.h) extern int load_aclfile();
 282   (.c) int load_aclfile(struct client_state *csp)</pre>
 283             </td>
 284           </tr>
 285         </table>
 286       </div>
 287       <div class="SECT3">
 288         <h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and #defines</a></h3>
 289         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 290         <p>Use all capital letters, with underscores between words. Do not start an identifier with an underscore.
 291         (ANSI C reserves these for use by the compiler and system headers.)</p>
 292         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 293         <table border="0" bgcolor="#E0E0E0" width="100%">
 294           <tr>
 295             <td>
 296               <pre class="PROGRAMLISTING">  (enumeration) : enum Boolean {FALSE, TRUE};
 297   (#define) : #define DEFAULT_SIZE 100;</pre>
 298             </td>
 299           </tr>
 300         </table>
 301         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> We have a standard naming scheme for #defines
 302         that toggle a feature in the preprocessor: FEATURE_&#62;, where &#62; is a short (preferably 1 or 2 word)
 303         description.</p>
 304         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 305         <table border="0" bgcolor="#E0E0E0" width="100%">
 306           <tr>
 307             <td>
 308               <pre class="PROGRAMLISTING">  #define FEATURE_FORCE 1
 309
 310   #ifdef FEATURE_FORCE
 311   #define FORCE_PREFIX blah
 312   #endif /* def FEATURE_FORCE */</pre>
 313             </td>
 314           </tr>
 315         </table>
 316       </div>
 317       <div class="SECT3">
 318         <h3 class="SECT3"><a name="S14" id="S14">4.3.5. Constants</a></h3>
 319         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 320         <p>Spell common words out entirely (do not remove vowels).</p>
 321         <p>Use only widely-known domain acronyms and abbreviations. Capitalize all letters of an acronym.</p>
 322         <p>Use underscore (_) to separate adjacent acronyms and abbreviations. Never terminate a name with an
 323         underscore.</p>
 324         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 325         <table border="0" bgcolor="#E0E0E0" width="100%">
 326           <tr>
 327             <td>
 328               <pre class="PROGRAMLISTING">  #define USE_IMAGE_LIST 1</pre>
 329             </td>
 330           </tr>
 331         </table>
 332         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 333         <table border="0" bgcolor="#E0E0E0" width="100%">
 334           <tr>
 335             <td>
 336               <pre class="PROGRAMLISTING">  #define USE_IMG_LST 1 or
 337   #define _USE_IMAGE_LIST 1 or
 338   #define USE_IMAGE_LIST_ 1 or
 339   #define use_image_list 1 or
 340   #define UseImageList 1</pre>
 341             </td>
 342           </tr>
 343         </table>
 344       </div>
 345     </div>
 346     <div class="SECT2">
 347       <h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
 348       <div class="SECT3">
 349         <h3 class="SECT3"><a name="S16" id="S16">4.4.1. Put braces on a line by themselves.</a></h3>
 350         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 351         <p>The brace needs to be on a line all by itself, not at the end of the statement. Curly braces should line up
 352         with the construct that they're associated with. This practice makes it easier to identify the opening and
 353         closing braces for a block.</p>
 354         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 355         <table border="0" bgcolor="#E0E0E0" width="100%">
 356           <tr>
 357             <td>
 358               <pre class="PROGRAMLISTING">  if (this == that)
 359   {
 360      ...
 361   }</pre>
 362             </td>
 363           </tr>
 364         </table>
 365         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 366         <p>if (this == that) { ... }</p>
 367         <p>or</p>
 368         <p>if (this == that) { ... }</p>
 369         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> In the special case that the if-statement is
 370         inside a loop, and it is trivial, i.e. it tests for a condition that is obvious from the purpose of the block,
 371         one-liners as above may optically preserve the loop structure and make it easier to read.</p>
 372         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> developer-discretion.</p>
 373         <p><span class="emphasis"><i class="EMPHASIS">Example exception:</i></span></p>
 374         <table border="0" bgcolor="#E0E0E0" width="100%">
 375           <tr>
 376             <td>
 377               <pre class="PROGRAMLISTING">  while (more lines are read)
 378   {
 379      /* Please document what is/is not a comment line here */
 380      if (it's a comment) continue;
 381
 382      do_something(line);
 383   }</pre>
 384             </td>
 385           </tr>
 386         </table>
 387       </div>
 388       <div class="SECT3">
 389         <h3 class="SECT3"><a name="S17" id="S17">4.4.2. ALL control statements should have a block</a></h3>
 390         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 391         <p>Using braces to make a block will make your code more readable and less prone to error. All control
 392         statements should have a block defined.</p>
 393         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 394         <table border="0" bgcolor="#E0E0E0" width="100%">
 395           <tr>
 396             <td>
 397               <pre class="PROGRAMLISTING">  if (this == that)
 398   {
 399      do_something();
 400      do_something_else();
 401   }</pre>
 402             </td>
 403           </tr>
 404         </table>
 405         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 406         <p>if (this == that) do_something(); do_something_else();</p>
 407         <p>or</p>
 408         <p>if (this == that) do_something();</p>
 409         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The first example in "Instead of" will execute
 410         in a manner other than that which the developer desired (per indentation). Using code braces would have
 411         prevented this "feature". The "explanation" and "exception" from the point above also applies.</p>
 412       </div>
 413       <div class="SECT3">
 414         <h3 class="SECT3"><a name="S18" id="S18">4.4.3. Do not belabor/blow-up boolean expressions</a></h3>
 415         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 416         <table border="0" bgcolor="#E0E0E0" width="100%">
 417           <tr>
 418             <td>
 419               <pre class="PROGRAMLISTING">  structure-&#62;flag = (condition);</pre>
 420             </td>
 421           </tr>
 422         </table>
 423         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 424         <p>if (condition) { structure-&#62;flag = 1; } else { structure-&#62;flag = 0; }</p>
 425         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The former is readable and concise. The later is
 426         wordy and inefficient. Please assume that any developer new to the project has at least a "good" knowledge of
 427         C/C++. (Hope I do not offend by that last comment ... 8-)</p>
 428       </div>
 429       <div class="SECT3">
 430         <h3 class="SECT3"><a name="S19" id="S19">4.4.4. Use white space freely because it is free</a></h3>
 431         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 432         <p>Make it readable. The notable exception to using white space freely is listed in the next guideline.</p>
 433         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 434         <table border="0" bgcolor="#E0E0E0" width="100%">
 435           <tr>
 436             <td>
 437               <pre class="PROGRAMLISTING">  int first_value   = 0;
 438   int some_value    = 0;
 439   int another_value = 0;
 440   int this_variable = 0;</pre>
 441             </td>
 442           </tr>
 443         </table>
 444       </div>
 445       <div class="SECT3">
 446         <h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space around structure operators</a></h3>
 447         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 448         <p>- structure pointer operator ( "-&#62;" ) - member operator ( "." ) - functions and parentheses</p>
 449         <p>It is a general coding practice to put pointers, references, and function parentheses next to names. With
 450         spaces, the connection between the object and variable/function name is not as clear.</p>
 451         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 452         <table border="0" bgcolor="#E0E0E0" width="100%">
 453           <tr>
 454             <td>
 455               <pre class="PROGRAMLISTING">  a_struct-&#62;a_member;
 456   a_struct.a_member;
 457   function_name();</pre>
 458             </td>
 459           </tr>
 460         </table>
 461         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span> a_struct -&#62; a_member; a_struct .
 462         a_member; function_name ();</p>
 463       </div>
 464       <div class="SECT3">
 465         <h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace of a function stand out</a></h3>
 466         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 467         <table border="0" bgcolor="#E0E0E0" width="100%">
 468           <tr>
 469             <td>
 470               <pre class="PROGRAMLISTING">  int function1( ... )
 471   {
 472      ...code...
 473      return(ret_code);
 474
 475   } /* -END- function1 */
 476
 477
 478   int function2( ... )
 479   {
 480   } /* -END- function2 */</pre>
 481             </td>
 482           </tr>
 483         </table>
 484         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 485         <p>int function1( ... ) { ...code... return(ret_code); } int function2( ... ) { }</p>
 486         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> Use 1 blank line before the closing brace and 2
 487         lines afterward. This makes the end of function standout to the most casual viewer. Although function comments
 488         help separate functions, this is still a good coding practice. In fact, I follow these rules when using blocks
 489         in "for", "while", "do" loops, and long if {} statements too. After all whitespace is free!</p>
 490         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> developer-discretion on the number of blank
 491         lines. Enforced is the end of function comments.</p>
 492       </div>
 493       <div class="SECT3">
 494         <h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character indentions</a></h3>
 495         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 496         <p>If some use 8 character TABs and some use 3 character TABs, the code can look *very* ragged. So use 3
 497         character indentions only. If you like to use TABs, pass your code through a filter such as "expand -t3" before
 498         checking in your code.</p>
 499         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 500         <table border="0" bgcolor="#E0E0E0" width="100%">
 501           <tr>
 502             <td>
 503               <pre class="PROGRAMLISTING">  static const char * const url_code_map[256] =
 504   {
 505      NULL, ...
 506   };
 507
 508
 509   int function1( ... )
 510   {
 511      if (1)
 512      {
 513         return ALWAYS_TRUE;
 514      }
 515      else
 516      {
 517         return HOW_DID_YOU_GET_HERE;
 518      }
 519
 520      return NEVER_GETS_HERE;
 521
 522   }</pre>
 523             </td>
 524           </tr>
 525         </table>
 526       </div>
 527     </div>
 528     <div class="SECT2">
 529       <h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
 530       <div class="SECT3">
 531         <h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all variables</a></h3>
 532         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 533         <p>Do not assume that the variables declared will not be used until after they have been assigned a value
 534         somewhere else in the code. Remove the chance of accidentally using an unassigned variable.</p>
 535         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 536         <table border="0" bgcolor="#E0E0E0" width="100%">
 537           <tr>
 538             <td>
 539               <pre class="PROGRAMLISTING">  short a_short = 0;
 540   float a_float  = 0;
 541   struct *ptr = NULL;</pre>
 542             </td>
 543           </tr>
 544         </table>
 545         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It is much easier to debug a SIGSEGV if the
 546         message says you are trying to access memory address 00000000 and not 129FA012; or array_ptr[20] causes a
 547         SIGSEV vs. array_ptr[0].</p>
 548         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> developer-discretion if and only if the
 549         variable is assigned a value "shortly after" declaration.</p>
 550       </div>
 551     </div>
 552     <div class="SECT2">
 553       <h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
 554       <div class="SECT3">
 555         <h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that return a boolean as a question.</a></h3>
 556         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 557         <p>Value should be phrased as a question that would logically be answered as a true or false statement</p>
 558         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 559         <table border="0" bgcolor="#E0E0E0" width="100%">
 560           <tr>
 561             <td>
 562               <pre class="PROGRAMLISTING">  should_we_block_this();
 563   contains_an_image();
 564   is_web_page_blank();</pre>
 565             </td>
 566           </tr>
 567         </table>
 568       </div>
 569       <div class="SECT3">
 570         <h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a return type for a function.</a></h3>
 571         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 572         <p>The default return for a function is an int. To avoid ambiguity, create a return for a function when the
 573         return has a purpose, and create a void return type if the function does not need to return anything.</p>
 574       </div>
 575       <div class="SECT3">
 576         <h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function calls when iterating by using
 577         variables</a></h3>
 578         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 579         <p>It is easy to write the following code, and a clear argument can be made that the code is easy to
 580         understand:</p>
 581         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 582         <table border="0" bgcolor="#E0E0E0" width="100%">
 583           <tr>
 584             <td>
 585               <pre class="PROGRAMLISTING">  for (size_t cnt = 0; cnt &lt; block_list_length(); cnt++)
 586   {
 587      ....
 588   }</pre>
 589             </td>
 590           </tr>
 591         </table>
 592         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> Unfortunately, this makes a function call for
 593         each and every iteration. This increases the overhead in the program, because the compiler has to look up the
 594         function each time, call it, and return a value. Depending on what occurs in the block_list_length() call, it
 595         might even be creating and destroying structures with each iteration, even though in each case it is comparing
 596         "cnt" to the same value, over and over. Remember too - even a call to block_list_length() is a function call,
 597         with the same overhead.</p>
 598         <p>Instead of using a function call during the iterations, assign the value to a variable, and evaluate using
 599         the variable.</p>
 600         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 601         <table border="0" bgcolor="#E0E0E0" width="100%">
 602           <tr>
 603             <td>
 604               <pre class="PROGRAMLISTING">  size_t len = block_list_length();
 605
 606   for (size_t cnt = 0; cnt &lt; len; cnt++)
 607   {
 608      ....
 609   }</pre>
 610             </td>
 611           </tr>
 612         </table>
 613         <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span> if the value of block_list_length() *may*
 614         change or could *potentially* change, then you must code the function call in the for/while loop.</p>
 615       </div>
 616       <div class="SECT3">
 617         <h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by Const Reference</a></h3>
 618         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 619         <p>This allows a developer to define a const pointer and call your function. If your function does not have the
 620         const keyword, we may not be able to use your function. Consider strcmp, if it were defined as: extern int
 621         strcmp(char *s1, char *s2);</p>
 622         <p>I could then not use it to compare argv's in main: int main(int argc, const char *argv[]) { strcmp(argv[0],
 623         "privoxy"); }</p>
 624         <p>Both these pointers are *const*! If the c runtime library maintainers do it, we should too.</p>
 625       </div>
 626       <div class="SECT3">
 627         <h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by Value</a></h3>
 628         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 629         <p>Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes or less). Aka, a function
 630         declaration like: int load_aclfile(struct client_state csp)</p>
 631         <p>would not work. So, to be consistent, we should declare all prototypes with "pass by value": int
 632         load_aclfile(struct client_state *csp)</p>
 633       </div>
 634       <div class="SECT3">
 635         <h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include files</a></h3>
 636         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 637         <p>Your include statements should contain the file name without a path. The path should be listed in the
 638         Makefile, using -I as processor directive to search the indicated paths. An exception to this would be for some
 639         proprietary software that utilizes a partial path to distinguish their header files from system or other header
 640         files.</p>
 641         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 642         <table border="0" bgcolor="#E0E0E0" width="100%">
 643           <tr>
 644             <td>
 645               <pre class="PROGRAMLISTING">  #include &lt;iostream.h&gt;     /* This is not a local include */
 646   #include "config.h"       /* This IS a local include */</pre>
 647             </td>
 648           </tr>
 649         </table>
 650         <p><span class="emphasis"><i class="EMPHASIS">Exception:</i></span></p>
 651         <table border="0" bgcolor="#E0E0E0" width="100%">
 652           <tr>
 653             <td>
 654               <pre class="PROGRAMLISTING">  /* This is not a local include, but requires a path element. */
 655   #include &lt;sys/fileName.h&gt;</pre>
 656             </td>
 657           </tr>
 658         </table>
 659         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> Please! do not add "-I." to the Makefile without
 660         a _very_ good reason. This duplicates the #include "file.h" behavior.</p>
 661       </div>
 662       <div class="SECT3">
 663         <h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple inclusion protection</a></h3>
 664         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 665         <p>Prevents compiler and linker errors resulting from redefinition of items.</p>
 666         <p>Wrap each header file with the following syntax to prevent multiple inclusions of the file. Of course,
 667         replace PROJECT_H with your file name, with "." Changed to "_", and make it uppercase.</p>
 668         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 669         <table border="0" bgcolor="#E0E0E0" width="100%">
 670           <tr>
 671             <td>
 672               <pre class="PROGRAMLISTING">  #ifndef PROJECT_H_INCLUDED
 673   #define PROJECT_H_INCLUDED
 674    ...
 675   #endif /* ndef PROJECT_H_INCLUDED */</pre>
 676             </td>
 677           </tr>
 678         </table>
 679       </div>
 680       <div class="SECT3">
 681         <h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when appropriate</a></h3>
 682         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 683         <p>If our headers are included from C++, they must declare our functions as `extern "C"`. This has no cost in
 684         C, but increases the potential re-usability of our code.</p>
 685         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 686         <table border="0" bgcolor="#E0E0E0" width="100%">
 687           <tr>
 688             <td>
 689               <pre class="PROGRAMLISTING">  #ifdef __cplusplus
 690   extern "C"
 691   {
 692   #endif /* def __cplusplus */
 693
 694   ... function definitions here ...
 695
 696   #ifdef __cplusplus
 697   }
 698   #endif /* def __cplusplus */</pre>
 699             </td>
 700           </tr>
 701         </table>
 702       </div>
 703       <div class="SECT3">
 704         <h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use Forward Struct Declaration Instead of
 705         Includes</a></h3>
 706         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 707         <p>Useful in headers that include pointers to other struct's. Modifications to excess header files may cause
 708         needless compiles.</p>
 709         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 710         <table border="0" bgcolor="#E0E0E0" width="100%">
 711           <tr>
 712             <td>
 713               <pre class="PROGRAMLISTING">  /*********************************************************************
 714    * We're avoiding an include statement here!
 715    *********************************************************************/
 716   struct file_list;
 717   extern file_list *xyz;</pre>
 718             </td>
 719           </tr>
 720         </table>
 721         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you declare "file_list xyz;" (without the
 722         pointer), then including the proper header file is necessary. If you only want to prototype a pointer, however,
 723         the header file is unnecessary.</p>
 724         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> Use with discretion.</p>
 725       </div>
 726     </div>
 727     <div class="SECT2">
 728       <h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding Practices</a></h2>
 729       <div class="SECT3">
 730         <h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on warnings</a></h3>
 731         <p><span class="emphasis"><i class="EMPHASIS">Explanation</i></span></p>
 732         <p>Compiler warnings are meant to help you find bugs. You should turn on as many as possible. With GCC, the
 733         switch is "-Wall". Try and fix as many warnings as possible.</p>
 734       </div>
 735       <div class="SECT3">
 736         <h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default case for all switch statements</a></h3>
 737         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 738         <p>What you think is guaranteed is never really guaranteed. The value that you don't think you need to check is
 739         the one that someday will be passed. So, to protect yourself from the unknown, always have a default step in a
 740         switch statement.</p>
 741         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 742         <table border="0" bgcolor="#E0E0E0" width="100%">
 743           <tr>
 744             <td>
 745               <pre class="PROGRAMLISTING">  switch (hash_string(cmd))
 746   {
 747      case hash_actions_file:
 748         ... code ...
 749         break;
 750
 751      case hash_confdir:
 752         ... code ...
 753         break;
 754
 755      default:
 756         log_error( ... );
 757         ... anomaly code goes here ...
 758         continue; / break; / exit( 1 ); / etc ...
 759
 760   } /* end switch (hash_string(cmd)) */</pre>
 761             </td>
 762           </tr>
 763         </table>
 764         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you already have a default condition, you are
 765         obviously exempt from this point. Of note, most of the WIN32 code calls `DefWindowProc' after the switch
 766         statement. This API call *should* be included in a default statement.</p>
 767         <p><span class="emphasis"><i class="EMPHASIS">Another Note:</i></span> This is not so much a readability issue
 768         as a robust programming issue. The "anomaly code goes here" may be no more than a print to the STDERR stream
 769         (as in load_config). Or it may really be an abort condition.</p>
 770         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> Programmer discretion is advised.</p>
 771       </div>
 772       <div class="SECT3">
 773         <h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling through cases in a switch
 774         statement.</a></h3>
 775         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 776         <p>In general, you will want to have a 'break' statement within each 'case' of a switch statement. This allows
 777         for the code to be more readable and understandable, and furthermore can prevent unwanted surprises if someone
 778         else later gets creative and moves the code around.</p>
 779         <p>The language allows you to plan the fall through from one case statement to another simply by omitting the
 780         break statement within the case statement. This feature does have benefits, but should only be used in rare
 781         cases. In general, use a break statement for each case statement.</p>
 782         <p>If you choose to allow fall through, you should comment both the fact of the fall through and reason why you
 783         felt it was necessary.</p>
 784       </div>
 785       <div class="SECT3">
 786         <h3 class="SECT3"><a name="S40" id="S40">4.7.4. Don't mix size_t and other types</a></h3>
 787         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 788         <p>The type of size_t varies across platforms. Do not make assumptions about whether it is signed or unsigned,
 789         or about how long it is. Do not compare a size_t against another variable of a different type (or even against
 790         a constant) without casting one of the values.</p>
 791       </div>
 792       <div class="SECT3">
 793         <h3 class="SECT3"><a name="S41" id="S41">4.7.5. Declare each variable and struct on its own line.</a></h3>
 794         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 795         <p>It can be tempting to declare a series of variables all on one line. Don't.</p>
 796         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 797         <table border="0" bgcolor="#E0E0E0" width="100%">
 798           <tr>
 799             <td>
 800               <pre class="PROGRAMLISTING">  long a = 0;
 801   long b = 0;
 802   long c = 0;</pre>
 803             </td>
 804           </tr>
 805         </table>
 806         <p><span class="emphasis"><i class="EMPHASIS">Instead of:</i></span></p>
 807         <p>long a, b, c;</p>
 808         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span> - there is more room for comments on the
 809         individual variables - easier to add new variables without messing up the original ones - when searching on a
 810         variable to find its type, there is less clutter to "visually" eliminate</p>
 811         <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span> when you want to declare a bunch of loop
 812         variables or other trivial variables; feel free to declare them on one line. You should, although, provide a
 813         good comment on their functions.</p>
 814         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> developer-discretion.</p>
 815       </div>
 816       <div class="SECT3">
 817         <h3 class="SECT3"><a name="S42" id="S42">4.7.6. Use malloc/zalloc sparingly</a></h3>
 818         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 819         <p>Create a local struct (on the stack) if the variable will live and die within the context of one function
 820         call.</p>
 821         <p>Only "malloc" a struct (on the heap) if the variable's life will extend beyond the context of one function
 822         call.</p>
 823         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 824         <table border="0" bgcolor="#E0E0E0" width="100%">
 825           <tr>
 826             <td>
 827               <pre class="PROGRAMLISTING">  If a function creates a struct and stores a pointer to it in a
 828   list, then it should definitely be allocated via `malloc'.</pre>
 829             </td>
 830           </tr>
 831         </table>
 832       </div>
 833       <div class="SECT3">
 834         <h3 class="SECT3"><a name="S43" id="S43">4.7.7. The Programmer Who Uses 'malloc' is Responsible for Ensuring
 835         'free'</a></h3>
 836         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 837         <p>If you have to "malloc" an instance, you are responsible for insuring that the instance is `free'd, even if
 838         the deallocation event falls within some other programmer's code. You are also responsible for ensuring that
 839         deletion is timely (i.e. not too soon, not too late). This is known as "low-coupling" and is a "good thing
 840         (tm)". You may need to offer a free/unload/destructor type function to accommodate this.</p>
 841         <p><span class="emphasis"><i class="EMPHASIS">Example:</i></span></p>
 842         <table border="0" bgcolor="#E0E0E0" width="100%">
 843           <tr>
 844             <td>
 845               <pre class="PROGRAMLISTING">  int load_re_filterfile(struct client_state *csp) { ... }
 846   static void unload_re_filterfile(void *f) { ... }</pre>
 847             </td>
 848           </tr>
 849         </table>
 850         <p><span class="emphasis"><i class="EMPHASIS">Exceptions:</i></span></p>
 851         <p>The developer cannot be expected to provide `free'ing functions for C run-time library functions ... such as
 852         `strdup'.</p>
 853         <p><span class="emphasis"><i class="EMPHASIS">Status:</i></span> developer-discretion. The "main" use of this
 854         standard is for allocating and freeing data structures (complex or nested).</p>
 855       </div>
 856       <div class="SECT3">
 857         <h3 class="SECT3"><a name="S44" id="S44">4.7.8. Add loaders to the `file_list' structure and in order</a></h3>
 858         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 859         <p>I have ordered all of the "blocker" file code to be in alpha order. It is easier to add/read new blockers
 860         when you expect a certain order.</p>
 861         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> It may appear that the alpha order is broken in
 862         places by POPUP tests coming before PCRS tests. But since POPUPs can also be referred to as KILLPOPUPs, it is
 863         clear that it should come first.</p>
 864       </div>
 865       <div class="SECT3">
 866         <h3 class="SECT3"><a name="S45" id="S45">4.7.9. "Uncertain" new code and/or changes to existing code, use
 867         XXX</a></h3>
 868         <p><span class="emphasis"><i class="EMPHASIS">Explanation:</i></span></p>
 869         <p>If you have enough confidence in new code or confidence in your changes, but are not *quite* sure of the
 870         repercussions, add this:</p>
 871         <p>/* XXX: this code has a logic error on platform XYZ, * attempting to fix */ #ifdef PLATFORM ...changed code
 872         here... #endif</p>
 873         <p>or:</p>
 874         <p>/* XXX: I think the original author really meant this... */ ...changed code here...</p>
 875         <p>or:</p>
 876         <p>/* XXX: new code that *may* break something else... */ ...new code here...</p>
 877         <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If you make it clear that this may or may not be
 878         a "good thing (tm)", it will be easier to identify and include in the project (or conversely exclude from the
 879         project).</p>
 880       </div>
 881     </div>
 882     <div class="SECT2">
 883       <h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for files and function comment blocks:</a></h2>
 884       <p><span class="emphasis"><i class="EMPHASIS">Example for file comments:</i></span></p>
 885       <table border="0" bgcolor="#E0E0E0" width="100%">
 886         <tr>
 887           <td>
 888             <pre class="PROGRAMLISTING">  /*********************************************************************
 889    *
 890    * File        :  $Source
 891    *
 892    * Purpose     :  (Fill me in with a good description!)
 893    *
 894    * Copyright   :  Written by and Copyright (C) 2001-2009
 895    *                the Privoxy team. https://www.privoxy.org/
 896    *
 897    *                This program is free software; you can redistribute it
 898    *                and/or modify it under the terms of the GNU General
 899    *                Public License as published by the Free Software
 900    *                Foundation; either version 2 of the License, or (at
 901    *                your option) any later version.
 902    *
 903    *                This program is distributed in the hope that it will
 904    *                be useful, but WITHOUT ANY WARRANTY; without even the
 905    *                implied warranty of MERCHANTABILITY or FITNESS FOR A
 906    *                PARTICULAR PURPOSE.  See the GNU General Public
 907    *                License for more details.
 908    *
 909    *                The GNU General Public License should be included with
 910    *                this file.  If not, you can view it at
 911    *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 912    *                or write to the Free Software Foundation, Inc.,
 913    *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
 914    *                USA
 915    *
 916    *********************************************************************/
 917
 918
 919   #include "config.h"
 920
 921      ...necessary include files for us to do our work...
 922
 923   const char FILENAME_h_rcs[] = FILENAME_H_VERSION;</pre>
 924           </td>
 925         </tr>
 926       </table>
 927       <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> This declares the rcs variables that should be
 928       added to the "show-version" page. If this is a brand new creation by you, you are free to change the "Copyright"
 929       section to represent the rights you wish to maintain.</p>
 930       <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> The formfeed character that is present right after
 931       the comment flower box is handy for (X|GNU)Emacs users to skip the verbiage and get to the heart of the code (via
 932       `forward-page' and `backward-page'). Please include it if you can.</p>
 933       <p><span class="emphasis"><i class="EMPHASIS">Example for file header comments:</i></span></p>
 934       <table border="0" bgcolor="#E0E0E0" width="100%">
 935         <tr>
 936           <td>
 937             <pre class="PROGRAMLISTING">  #ifndef _FILENAME_H
 938   #define _FILENAME_H
 939   /*********************************************************************
 940    *
 941    * File        :  $Source
 942    *
 943    * Purpose     :  (Fill me in with a good description!)
 944    *
 945    * Copyright   :  Written by and Copyright (C) 2001-2009
 946    *                the Privoxy team. https://www.privoxy.org/
 947    *
 948    *                This program is free software; you can redistribute it
 949    *                and/or modify it under the terms of the GNU General
 950    *                Public License as published by the Free Software
 951    *                Foundation; either version 2 of the License, or (at
 952    *                your option) any later version.
 953    *
 954    *                This program is distributed in the hope that it will
 955    *                be useful, but WITHOUT ANY WARRANTY; without even the
 956    *                implied warranty of MERCHANTABILITY or FITNESS FOR A
 957    *                PARTICULAR PURPOSE.  See the GNU General Public
 958    *                License for more details.
 959    *
 960    *                The GNU General Public License should be included with
 961    *                this file.  If not, you can view it at
 962    *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
 963    *                or write to the Free Software Foundation, Inc.,
 964    *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
 965    *                USA
 966    *
 967    *********************************************************************/
 968
 969
 970   #include "project.h"
 971
 972   #ifdef __cplusplus
 973   extern "C" {
 974   #endif
 975
 976      ... function headers here ...
 977
 978
 979   /* Revision control strings from this header and associated .c file */
 980   extern const char FILENAME_rcs[];
 981   extern const char FILENAME_h_rcs[];
 982
 983
 984   #ifdef __cplusplus
 985   } /* extern "C" */
 986   #endif
 987
 988   #endif /* ndef _FILENAME_H */
 989
 990   /*
 991     Local Variables:
 992     tab-width: 3
 993     end:
 994   */</pre>
 995           </td>
 996         </tr>
 997       </table>
 998       <p><span class="emphasis"><i class="EMPHASIS">Example for function comments:</i></span></p>
 999       <table border="0" bgcolor="#E0E0E0" width="100%">
1000         <tr>
1001           <td>
1002             <pre class="PROGRAMLISTING">  /*********************************************************************
1003    *
1004    * Function    :  FUNCTION_NAME
1005    *
1006    * Description :  (Fill me in with a good description!)
1007    *
1008    * parameters  :
1009    *          1  :  param1 = pointer to an important thing
1010    *          2  :  x      = pointer to something else
1011    *
1012    * Returns     :  0 =&#62; Ok, everything else is an error.
1013    *
1014    *********************************************************************/
1015   int FUNCTION_NAME(void *param1, const char *x)
1016   {
1017      ...
1018      return 0;
1019
1020   }</pre>
1021           </td>
1022         </tr>
1023       </table>
1024       <p><span class="emphasis"><i class="EMPHASIS">Note:</i></span> If we all follow this practice, we should be able
1025       to parse our code to create a "self-documenting" web page.</p>
1026     </div>
1027   </div>
1028   <div class="NAVFOOTER">
1029     <hr align="left" width="100%">
1030     <table summary="Footer navigation table" width="100%" border="0" cellpadding="0" cellspacing="0">
1031       <tr>
1032         <td width="33%" align="left" valign="top"><a href="documentation.html" accesskey="P">Prev</a></td>
1033         <td width="34%" align="center" valign="top"><a href="index.html" accesskey="H">Home</a></td>
1034         <td width="33%" align="right" valign="top"><a href="testing.html" accesskey="N">Next</a></td>
1035       </tr>
1036       <tr>
1037         <td width="33%" align="left" valign="top">Documentation Guidelines</td>
1038         <td width="34%" align="center" valign="top">&nbsp;</td>
1039         <td width="33%" align="right" valign="top">Testing Guidelines</td>
1040       </tr>
1041     </table>
1042   </div>
1043 </body>
1044 </html>