+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN""http://www.w3.org/TR/html4/loose.dtd">
<HTML
><HEAD
><TITLE
>Coding Guidelines</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
-"><LINK
+CONTENT="Modular DocBook HTML Stylesheet Version 1.79"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
HREF="index.html"><LINK
HREF="testing.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
-HREF="../p_doc.css"></HEAD
+HREF="../p_doc.css"><META
+HTTP-EQUIV="Content-Type"
+CONTENT="text/html;
+charset=ISO-8859-1"></HEAD
><BODY
CLASS="SECT1"
BGCOLOR="#EEEEEE"
><H1
CLASS="SECT1"
><A
-NAME="CODING">4. Coding Guidelines</H1
+NAME="CODING"
+>4. Coding Guidelines</A
+></H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
-NAME="S1">4.1. Introduction</H2
+NAME="S1"
+>4.1. Introduction</A
+></H2
><P
>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
><H2
CLASS="SECT2"
><A
-NAME="S2">4.2. Using Comments</H2
+NAME="S2"
+>4.2. Using Comments</A
+></H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S3">4.2.1. Comment, Comment, Comment</H3
+NAME="S3"
+>4.2.1. Comment, Comment, Comment</A
+></H3
><P
><SPAN
CLASS="emphasis"
></P
><P
>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
><PRE
CLASS="PROGRAMLISTING"
>/* 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 ...
}
><H3
CLASS="SECT3"
><A
-NAME="S4">4.2.2. Use blocks for comments</H3
+NAME="S4"
+>4.2.2. Use blocks for comments</A
+></H3
><P
><SPAN
CLASS="emphasis"
>/*********************************************************************
* 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();
}</PRE
></TD
></TR
><H3
CLASS="SECT3"
><A
-NAME="S5">4.2.3. Keep Comments on their own line</H3
+NAME="S5"
+>4.2.3. Keep Comments on their own line</A
+></H3
><P
><SPAN
CLASS="emphasis"
* This will stand out clearly in your code,
* But the second example won't.
*********************************************************************/
-if ( thisVariable == thatVariable )
+if ( this_variable == this_variable )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
}
-if ( thisVariable == thatVariable ) /*can you see me?*/
+if ( this_variable == this_variable ) /*can you see me?*/
{
- DoSomethingVeryImportant(); /*not easily*/
+ do_something_very_important(); /*not easily*/
}
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
}
-short DoSomethingVeryImportant(
+short do_something_very_important(
short firstparam, /* represents something */
short nextparam /* represents something else */ )
{
...code here...
-} /* -END- DoSomethingVeryImportant */</PRE
+} /* -END- do_something_very_important */</PRE
></TD
></TR
></TABLE
><H3
CLASS="SECT3"
><A
-NAME="S6">4.2.4. Comment each logical step</H3
+NAME="S6"
+>4.2.4. Comment each logical step</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S7">4.2.5. Comment All Functions Thoroughly</H3
+NAME="S7"
+>4.2.5. Comment All Functions Thoroughly</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S8">4.2.6. Comment at the end of braces if the
- content is more than one screen length</H3
+NAME="S8"
+>4.2.6. Comment at the end of braces if the
+ content is more than one screen length</A
+></H3
><P
><SPAN
CLASS="emphasis"
CLASS="PROGRAMLISTING"
>if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if x is 1 */
if ( 1 == X )
{
- DoSomethingVeryImportant();
+ do_something_very_important();
...some long list of commands...
} /* -END- if ( 1 == X ) */</PRE
></TD
><H2
CLASS="SECT2"
><A
-NAME="S9">4.3. Naming Conventions</H2
+NAME="S9"
+>4.3. Naming Conventions</A
+></H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S10">4.3.1. Variable Names</H3
+NAME="S10"
+>4.3.1. Variable Names</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S11">4.3.2. Function Names</H3
+NAME="S11"
+>4.3.2. Function Names</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S12">4.3.3. Header file prototypes</H3
+NAME="S12"
+>4.3.3. Header file prototypes</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S13">4.3.4. Enumerations, and #defines</H3
+NAME="S13"
+>4.3.4. Enumerations, and #defines</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S14">4.3.5. Constants</H3
+NAME="S14"
+>4.3.5. Constants</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H2
CLASS="SECT2"
><A
-NAME="S15">4.4. Using Space</H2
+NAME="S15"
+>4.4. Using Space</A
+></H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S16">4.4.1. Put braces on a line by themselves.</H3
+NAME="S16"
+>4.4.1. Put braces on a line by themselves.</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S17">4.4.2. ALL control statements should have a
- block</H3
+NAME="S17"
+>4.4.2. ALL control statements should have a
+ block</A
+></H3
><P
><SPAN
CLASS="emphasis"
CLASS="PROGRAMLISTING"
>if ( this == that )
{
- DoSomething();
- DoSomethingElse();
+ do_something();
+ do_something_else();
}</PRE
></TD
></TR
></SPAN
></P
><P
->if ( this == that ) DoSomething(); DoSomethingElse();</P
+>if ( this == that ) do_something(); do_something_else();</P
><P
>or</P
><P
->if ( this == that ) DoSomething();</P
+>if ( this == that ) do_something();</P
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S18">4.4.3. Do not belabor/blow-up boolean
- expressions</H3
+NAME="S18"
+>4.4.3. Do not belabor/blow-up boolean
+ expressions</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S19">4.4.4. Use white space freely because it is
- free</H3
+NAME="S19"
+>4.4.4. Use white space freely because it is
+ free</A
+></H3
><P
><SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
->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 )</PRE
+first_value = old_value + ( ( some_value - another_value ) - whatever )</PRE
></TD
></TR
></TABLE
><H3
CLASS="SECT3"
><A
-NAME="S20">4.4.5. Don't use white space around structure
- operators</H3
+NAME="S20"
+>4.4.5. Don't use white space around structure
+ operators</A
+></H3
><P
><SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
->aStruct->aMember;
-aStruct.aMember;
-FunctionName();</PRE
+>a_struct->a_member;
+a_struct.a_member;
+function_name();</PRE
></TD
></TR
></TABLE
CLASS="EMPHASIS"
>Instead of:</I
></SPAN
-> aStruct -> aMember; aStruct . aMember;
- FunctionName ();</P
+> a_struct -> a_member; a_struct . a_member;
+ function_name ();</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S21">4.4.6. Make the last brace of a function stand
- out</H3
+NAME="S21"
+>4.4.6. Make the last brace of a function stand
+ out</A
+></H3
><P
><SPAN
CLASS="emphasis"
>int function1( ... )
{
...code...
- return( retCode );
+ return( ret_code );
} /* -END- function1 */
></SPAN
></P
><P
->int function1( ... ) { ...code... return( retCode ); } int
+>int function1( ... ) { ...code... return( ret_code ); } int
function2( ... ) { }</P
><P
><SPAN
><H3
CLASS="SECT3"
><A
-NAME="S22">4.4.7. Use 3 character indentions</H3
+NAME="S22"
+>4.4.7. Use 3 character indentions</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H2
CLASS="SECT2"
><A
-NAME="S23">4.5. Initializing</H2
+NAME="S23"
+>4.5. Initializing</A
+></H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S24">4.5.1. Initialize all variables</H3
+NAME="S24"
+>4.5.1. Initialize all variables</A
+></H3
><P
><SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
->short anShort = 0;
-float aFloat = 0;
+>short a_short = 0;
+float a_float = 0;
struct *ptr = NULL;</PRE
></TD
></TR
></SPAN
> 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].</P
+ and not 129FA012; or array_ptr[20] causes a SIGSEV vs.
+ array_ptr[0].</P
><P
><SPAN
CLASS="emphasis"
><H2
CLASS="SECT2"
><A
-NAME="S25">4.6. Functions</H2
+NAME="S25"
+>4.6. Functions</A
+></H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S26">4.6.1. Name functions that return a boolean as a
- question.</H3
+NAME="S26"
+>4.6.1. Name functions that return a boolean as a
+ question.</A
+></H3
><P
><SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
->ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();</PRE
+>should_we_block_this();
+contains_an_image();
+is_web_page_blank();</PRE
></TD
></TR
></TABLE
><H3
CLASS="SECT3"
><A
-NAME="S27">4.6.2. Always specify a return type for a
- function.</H3
+NAME="S27"
+>4.6.2. Always specify a return type for a
+ function.</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S28">4.6.3. Minimize function calls when iterating by
- using variables</H3
+NAME="S28"
+>4.6.3. Minimize function calls when iterating by
+ using variables</A
+></H3
><P
><SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
->for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+>for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
{
....
}</PRE
each and every iteration. This increases the overhead in the
program, because the compiler has to look up the function each
time, call it, and return a value. Depending on what occurs in
- the blockListLength() call, it might even be creating and
+ the block_list_length() call, it might even be creating and
destroying structures with each iteration, even though in each
case it is comparing "cnt" to the same value, over and over.
- Remember too - even a call to blockListLength() is a function
+ Remember too - even a call to block_list_length() is a function
call, with the same overhead.</P
><P
>Instead of using a function call during the iterations,
><TD
><PRE
CLASS="PROGRAMLISTING"
->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++ )
{
....
}</PRE
CLASS="EMPHASIS"
>Exceptions:</I
></SPAN
-> 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.</P
></DIV
><DIV
><H3
CLASS="SECT3"
><A
-NAME="S29">4.6.4. Pass and Return by Const Reference</H3
+NAME="S29"
+>4.6.4. Pass and Return by Const Reference</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S30">4.6.5. Pass and Return by Value</H3
+NAME="S30"
+>4.6.5. Pass and Return by Value</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S31">4.6.6. Names of include files</H3
+NAME="S31"
+>4.6.6. Names of include files</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S32">4.6.7. Provide multiple inclusion
- protection</H3
+NAME="S32"
+>4.6.7. Provide multiple inclusion
+ protection</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S33">4.6.8. Use `extern "C"` when appropriate</H3
+NAME="S33"
+>4.6.8. Use `extern "C"` when appropriate</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S34">4.6.9. Where Possible, Use Forward Struct
- Declaration Instead of Includes</H3
+NAME="S34"
+>4.6.9. Where Possible, Use Forward Struct
+ Declaration Instead of Includes</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H2
CLASS="SECT2"
><A
-NAME="S35">4.7. General Coding Practices</H2
+NAME="S35"
+>4.7. General Coding Practices</A
+></H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S36">4.7.1. Turn on warnings</H3
+NAME="S36"
+>4.7.1. Turn on warnings</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S37">4.7.2. Provide a default case for all switch
- statements</H3
+NAME="S37"
+>4.7.2. Provide a default case for all switch
+ statements</A
+></H3
><P
><SPAN
CLASS="emphasis"
> 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.</P
+ load_config). Or it may really be an abort condition.</P
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S38">4.7.3. Try to avoid falling through cases in a
- switch statement.</H3
+NAME="S38"
+>4.7.3. Try to avoid falling through cases in a
+ switch statement.</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S39">4.7.4. Use 'long' or 'short' Instead of
- 'int'</H3
+NAME="S39"
+>4.7.4. Use 'long' or 'short' Instead of
+ 'int'</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S40">4.7.5. Don't mix size_t and other types</H3
+NAME="S40"
+>4.7.5. Don't mix size_t and other types</A
+></H3
><P
><SPAN
CLASS="emphasis"
assumptions about whether it is signed or unsigned, or about
how long it is. Do not compare a size_t against another
variable of a different type (or even against a constant)
- without casting one of the values. Try to avoid using size_t if
- you can.</P
+ without casting one of the values.</P
></DIV
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S41">4.7.6. Declare each variable and struct on its
- own line.</H3
+NAME="S41"
+>4.7.6. Declare each variable and struct on its
+ own line.</A
+></H3
><P
><SPAN
CLASS="emphasis"
></SPAN
> 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.</P
><P
><SPAN
><H3
CLASS="SECT3"
><A
-NAME="S42">4.7.7. Use malloc/zalloc sparingly</H3
+NAME="S42"
+>4.7.7. Use malloc/zalloc sparingly</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S43">4.7.8. The Programmer Who Uses 'malloc' is
- Responsible for Ensuring 'free'</H3
+NAME="S43"
+>4.7.8. The Programmer Who Uses 'malloc' is
+ Responsible for Ensuring 'free'</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S44">4.7.9. Add loaders to the `file_list' structure
- and in order</H3
+NAME="S44"
+>4.7.9. Add loaders to the `file_list' structure
+ and in order</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H3
CLASS="SECT3"
><A
-NAME="S45">4.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME</H3
+NAME="S45"
+>4.7.10. "Uncertain" new code and/or changes to
+ existing code, use FIXME or XXX</A
+></H3
><P
><SPAN
CLASS="emphasis"
><H2
CLASS="SECT2"
><A
-NAME="S46">4.8. Addendum: Template for files and function
- comment blocks:</H2
+NAME="S46"
+>4.8. Addendum: Template for files and function
+ comment blocks:</A
+></H2
><P
><SPAN
CLASS="emphasis"
><TD
><PRE
CLASS="PROGRAMLISTING"
->const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.3 2002/09/05 02:27:59 hal9 Exp $";
+>const char FILENAME_rcs[] = "$Id$";
/*********************************************************************
*
* File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 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
*
* 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.
- *
- * Revisions :
- * $Log$
+ * 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
*
*********************************************************************/
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$"
/*********************************************************************
*
* File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001 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
*
* 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.
- *
- * Revisions :
- * $Log$
+ * 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
*
*********************************************************************/
></DIV
></BODY
></HTML
->
\ No newline at end of file
+>
projects / privoxy.git / blobdiff