doc/standards.html

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