Coding Guidelines

4.1. Introduction

This set of standards is designed to make our lives easier. It is developed with the simple goal of helping us keep the "new and improved @@ -105,16 +108,16 @@ CLASS="SECT2" CLASS="SECT2" >4.2. Using Comments4.2. Using Comments

4.2.1. Comment, Comment, Comment

Comment as much as possible without commenting the obvious. - For example do not comment "aVariable is equal to bVariable". - Instead explain why aVariable should be equal to the bVariable. + For example do not comment "variable_a is equal to variable_b". + Instead explain why variable_a should be equal to the variable_b. Just because a person can read code does not mean they will understand why or what is being done. A reader may spend a lot more time figuring out what is going on when a simple comment @@ -153,13 +156,13 @@ WIDTH="100%" >

/* if page size greater than 1k ... */
-if ( PageLength() > 1024 )
+if ( page_length() > 1024 )
 {
     ... "block" the page up ...
 }
 
 /* if page size is small, send it in blocks */
-if ( PageLength() > 1024 )
+if ( page_length() > 1024 )
 {
     ... "block" the page up ...
 }
@@ -177,8 +180,8 @@ CLASS="SECT3"
 CLASS="SECT3"
 >4.2.2. Use blocks for comments4.2.2. Use blocks for comments/*********************************************************************
  * This will stand out clearly in your code!
  *********************************************************************/
-if ( thisVariable == thatVariable )
+if ( this_variable == that_variable )
 {
-   DoSomethingVeryImportant();
+   do_something_very_important();
 }
 
 
 /* unfortunately, this may not */
-if ( thisVariable == thatVariable )
+if ( this_variable == that_variable )
 {
-   DoSomethingVeryImportant();
+   do_something_very_important();
 }
 
 
-if ( thisVariable == thatVariable ) /* this may not either */
+if ( this_variable == that_variable ) /* this may not either */
 {
-   DoSomethingVeryImportant();
+   do_something_very_important();
 }

4.2.3. Keep Comments on their own line4.2.3. Keep Comments on their own line

4.2.4. Comment each logical step4.2.4. Comment each logical step

4.2.5. Comment All Functions Thoroughly4.2.5. Comment All Functions Thoroughly

4.2.6. Comment at the end of braces if the - content is more than one screen length

if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if x is 1 */ @@ -438,7 +441,7 @@ or: if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if ( 1 == X ) */4.3. Naming Conventions4.3. Naming Conventions

4.3.1. Variable Names

4.3.2. Function Names4.3.2. Function Names

4.3.3. Header file prototypes4.3.3. Header file prototypes

4.3.4. Enumerations, and #defines4.3.4. Enumerations, and #defines

4.3.5. Constants4.3.5. Constants

4.4. Using Space4.4. Using Space

4.4.1. Put braces on a line by themselves.

4.4.2. ALL control statements should have a - block

if ( this == that ) { - DoSomething(); - DoSomethingElse(); + do_something(); + do_something_else(); }

if ( this == that ) DoSomething(); DoSomethingElse();

if ( this == that ) do_something(); do_something_else();

if ( this == that ) DoSomething();

if ( this == that ) do_something();

4.4.3. Do not belabor/blow-up boolean - expressions

4.4.4. Use white space freely because it is - free

int firstValue   = 0;
-int someValue    = 0;
-int anotherValue = 0;
-int thisVariable = 0;
+>int first_value   = 0;
+int some_value    = 0;
+int another_value = 0;
+int this_variable = 0;
 
-if ( thisVariable == thatVariable )
+if ( this_variable == this_variable )
 
-firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )

4.4.5. Don't use white space around structure - operators

aStruct->aMember;
-aStruct.aMember;
-FunctionName();

a_struct->a_member; +a_struct.a_member; +function_name();Instead of: aStruct -> aMember; aStruct . aMember; - FunctionName ();

a_struct -> a_member; a_struct . a_member; + function_name ();

4.4.6. Make the last brace of a function stand - out

int function1( ... ) { ...code... - return( retCode ); + return( ret_code ); } /* -END- function1 */ @@ -1191,7 +1194,7 @@ CLASS="EMPHASIS" >

int function1( ... ) { ...code... return( retCode ); } int +>int function1( ... ) { ...code... return( ret_code ); } int function2( ... ) { }

4.4.7. Use 3 character indentions4.4.7. Use 3 character indentions

4.5. Initializing4.5. Initializing

4.5.1. Initialize all variables

short anShort = 0;
-float aFloat  = 0;
+>short a_short = 0;
+float a_float  = 0;
 struct *ptr = NULL;

It is much easier to debug a SIGSEGV if the message says you are trying to access memory address 00000000 - and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. - arrayPtr[0].

4.6. Functions4.6. Functions

4.6.1. Name functions that return a boolean as a - question.

ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();

should_we_block_this(); +contains_an_image(); +is_web_page_blank();4.6.2. Always specify a return type for a - function.

4.6.3. Minimize function calls when iterating by - using variables

for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+>for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
 {
    ....
 }

Instead of using a function call during the iterations, @@ -1505,9 +1508,9 @@ WIDTH="100%" >

size_t len = blockListLength();
+>size_t len = block_list_length();
 
-for ( size_t cnt = 0; cnt < len; cnt ++ )
+for ( size_t cnt = 0; cnt < len; cnt++ )
 {
    ....
 }

Exceptions: if the value of blockListLength() *may* - change or could *potentially* change, then you must code the +> if the value of block_list_length() + *may* change or could *potentially* change, then you must code the function call in the for/while loop.

4.6.4. Pass and Return by Const Reference4.6.4. Pass and Return by Const Reference

4.6.5. Pass and Return by Value4.6.5. Pass and Return by Value

4.6.6. Names of include files4.6.6. Names of include files

4.6.7. Provide multiple inclusion - protection

4.6.8. Use `extern "C"` when appropriate4.6.8. Use `extern "C"` when appropriate

4.6.9. Where Possible, Use Forward Struct - Declaration Instead of Includes

4.7. General Coding Practices4.7. General Coding Practices

4.7.1. Turn on warnings

4.7.2. Provide a default case for all switch - statements

This is not so much a readability issue as a robust programming issue. The "anomaly code goes here" may be no more than a print to the STDERR stream (as in - load_config). Or it may really be an ABEND condition.

4.7.3. Try to avoid falling through cases in a - switch statement.

4.7.4. Use 'long' or 'short' Instead of - 'int'

4.7.5. Don't mix size_t and other types4.7.5. Don't mix size_t and other types

4.7.6. Declare each variable and struct on its - own line.

when you want to declare a bunch of loop variables or other trivial variables; feel free to declare them - on 1 line. You should, although, provide a good comment on + on one line. You should, although, provide a good comment on their functions.

4.7.7. Use malloc/zalloc sparingly4.7.7. Use malloc/zalloc sparingly

4.7.8. The Programmer Who Uses 'malloc' is - Responsible for Ensuring 'free'

4.7.9. Add loaders to the `file_list' structure - and in order

4.7.10. "Uncertain" new code and/or changes to - existing code, use FIXME

4.8. Addendum: Template for files and function - comment blocks:

const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $";
+>const char FILENAME_rcs[] = "$Id$";
 /*********************************************************************
  *
  * File        :  $Source$
  *
  * Purpose     :  (Fill me in with a good description!)
  *
- * Copyright   :  Written by and Copyright (C) 2001-2006 the SourceForge
- *                Privoxy team. http://www.privoxy.org/
- *
- *                Based on the Internet Junkbuster originally written
- *                by and Copyright (C) 1997 Anonymous Coders and
- *                Junkbusters Corporation.  http://www.junkbusters.com
+ * Copyright   :  Written by and Copyright (C) 2001-2009
+ *                the Privoxy team. http://www.privoxy.org/
  *
  *                This program is free software; you can redistribute it
  *                and/or modify it under the terms of the GNU General
@@ -2362,7 +2360,7 @@ CLASS="PROGRAMLISTING"
  *
  *                The GNU General Public License should be included with
  *                this file.  If not, you can view it at
- *                http://www.gnu.org/copyleft/gpl.html
+ *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
  *                or write to the Free Software Foundation, Inc., 
  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
  *                USA
@@ -2422,19 +2420,15 @@ WIDTH="100%"
 CLASS="PROGRAMLISTING"
 >#ifndef _FILENAME_H
 #define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.11 2006/09/26 02:36:29 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id$"
 /*********************************************************************
  *
  * File        :  $Source$
  *
  * Purpose     :  (Fill me in with a good description!)
  *
- * Copyright   :  Written by and Copyright (C) 2001-2006 the SourceForge
- *                Privoxy team. http://www.privoxy.org/
- *
- *                Based on the Internet Junkbuster originally written
- *                by and Copyright (C) 1997 Anonymous Coders and
- *                Junkbusters Corporation.  http://www.junkbusters.com
+ * Copyright   :  Written by and Copyright (C) 2001-2009
+ *                the Privoxy team. http://www.privoxy.org/
  *
  *                This program is free software; you can redistribute it
  *                and/or modify it under the terms of the GNU General
@@ -2450,7 +2444,7 @@ CLASS="PROGRAMLISTING"
  *
  *                The GNU General Public License should be included with
  *                this file.  If not, you can view it at
- *                http://www.gnu.org/copyleft/gpl.html
+ *                http://www.gnu.org/licenses/old-licenses/gpl-2.0.html
  *                or write to the Free Software Foundation, Inc., 
  *                51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
  *                USA