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 @@ -100,13 +104,17 @@ CLASS="SECT2" >
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 @@ -145,13 +153,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 ...
}
@@ -168,7 +176,9 @@ CLASS="SECT3"
>4.2.2. Use blocks for comments
4.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();
}
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if x is 1 */
@@ -420,7 +438,7 @@ or:
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if ( 1 == X ) */ if ( this == that )
{
- DoSomething();
- DoSomethingElse();
+ do_something();
+ do_something_else();
} if ( this == that ) DoSomething(); DoSomethingElse(); or if ( this == that ) DoSomething(); int function1( ... )
{
...code...
- return( retCode );
+ return( ret_code );
} /* -END- function1 */
@@ -1147,7 +1191,7 @@ CLASS="EMPHASIS"
> int function1( ... ) { ...code... return( retCode ); } int
+>int function1( ... ) { ...code... return( ret_code ); } int
function2( ... ) { } Instead of using a function call during the iterations,
@@ -1447,9 +1505,9 @@ WIDTH="100%"
> 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. 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.2.4. Comment each logical step
4.2.4. Comment each logical step4.2.5. Comment All Functions Thoroughly
4.2.5. Comment All Functions Thoroughly4.2.6. Comment at the end of braces if the
- content is more than one screen length
4.2.6. Comment at the end of braces if the
+ content is more than one screen length4.3. Naming Conventions
4.3. Naming Conventions4.3.1. Variable Names
4.3.1. Variable Names4.3.2. Function Names
4.3.2. Function Names4.3.3. Header file prototypes
4.3.3. Header file prototypes4.3.4. Enumerations, and #defines
4.3.4. Enumerations, and #defines4.3.5. Constants
4.3.5. Constants4.4. Using Space
4.4. Using Space4.4.1. Put braces on a line by themselves.
4.4.1. Put braces on a line by themselves.4.4.2. ALL control statements should have a
- block
4.4.2. ALL control statements should have a
+ block4.4.3. Do not belabor/blow-up boolean
- expressions
4.4.3. Do not belabor/blow-up boolean
+ expressions4.4.4. Use white space freely because it is
- free
4.4.4. Use white space freely because it is
+ freeint 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
4.4.5. Don't use white space around structure
+ operatorsaStruct->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
4.4.6. Make the last brace of a function stand
+ out4.4.7. Use 3 character indentions
4.4.7. Use 3 character indentions4.5. Initializing
4.5. Initializing4.5.1. Initialize all variables
4.5.1. Initialize all variablesshort anShort = 0;
-float aFloat = 0;
+>short a_short = 0;
+float a_float = 0;
struct *ptr = NULL;
4.6. Functions
4.6. Functions4.6.1. Name functions that return a boolean as a
- question.
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.2. Always specify a return type for a
+ function.4.6.3. Minimize function calls when iterating by
- using variables
4.6.3. Minimize function calls when iterating by
+ using variablesfor ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+>for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
{
....
}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 Reference
4.6.4. Pass and Return by Const Reference4.6.5. Pass and Return by Value
4.6.5. Pass and Return by Value4.6.6. Names of include files
4.6.6. Names of include files4.6.7. Provide multiple inclusion
- protection
4.6.7. Provide multiple inclusion
+ protection4.6.8. Use `extern "C"` when appropriate
4.6.8. Use `extern "C"` when appropriate4.6.9. Where Possible, Use Forward Struct
- Declaration Instead of Includes
4.6.9. Where Possible, Use Forward Struct
+ Declaration Instead of Includes4.7. General Coding Practices
4.7. General Coding Practices4.7.1. Turn on warnings
4.7.1. Turn on warnings4.7.2. Provide a default case for all switch
- statements
4.7.2. Provide a default case for all switch
+ statements4.7.3. Try to avoid falling through cases in a
- switch statement.
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.4. Use 'long' or 'short' Instead of
+ 'int'4.7.5. Don't mix size_t and other types
4.7.5. Don't mix size_t and other types4.7.6. Declare each variable and struct on its
- own line.
4.7.6. Declare each variable and struct on its
+ own line.4.7.7. Use malloc/zalloc sparingly
4.7.7. Use malloc/zalloc sparingly4.7.8. The Programmer Who Uses 'malloc' is
- Responsible for Ensuring 'free'
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.9. Add loaders to the `file_list' structure
+ and in order4.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME
4.7.10. "Uncertain" new code and/or changes to
+ existing code, use FIXME or XXX4.8. Addendum: Template for files and function
- comment blocks:
4.8. Addendum: Template for files and function
+ comment blocks:const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.3 2002/09/05 02:27:59 hal9 Exp $";
+>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.13 2007/10/30 17:59:31 fabiankeil Exp $";
/*********************************************************************
*
* File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
* Privoxy team. http://www.privoxy.org/
*
* Based on the Internet Junkbuster originally written
@@ -2269,8 +2362,9 @@ 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
- * or write to the Free Software Foundation, Inc., 59
- * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ * or write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
+ * USA
*
* Revisions :
* $Log$
@@ -2327,14 +2421,14 @@ WIDTH="100%"
CLASS="PROGRAMLISTING"
>#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.3 2002/09/05 02:27:59 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.13 2007/10/30 17:59:31 fabiankeil Exp $"
/*********************************************************************
*
* File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
+ * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge
* Privoxy team. http://www.privoxy.org/
*
* Based on the Internet Junkbuster originally written
@@ -2356,8 +2450,9 @@ 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
- * or write to the Free Software Foundation, Inc., 59
- * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
+ * or write to the Free Software Foundation, Inc.,
+ * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
+ * USA
*
* Revisions :
* $Log$