+<!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.64
-"><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"
><DIV
CLASS="NAVHEADER"
><TABLE
+SUMMARY="Header navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
VALIGN="bottom"
><A
HREF="documentation.html"
+ACCESSKEY="P"
>Prev</A
></TD
><TD
VALIGN="bottom"
><A
HREF="testing.html"
+ACCESSKEY="N"
>Next</A
></TD
></TR
CLASS="SECT1"
><A
NAME="CODING"
->6. Coding Guidelines</A
+>4. Coding Guidelines</A
></H1
><DIV
CLASS="SECT2"
CLASS="SECT2"
><A
NAME="S1"
->6.1. Introduction</A
+>4.1. Introduction</A
></H2
><P
>This set of standards is designed to make our lives easier. It is
CLASS="SECT2"
><A
NAME="S2"
->6.2. Using Comments</A
+>4.2. Using Comments</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S3"
->6.2.1. Comment, Comment, Comment</A
+>4.2.1. Comment, Comment, Comment</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></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
If the comment describes something different than what the code
is doing then maybe a programming error is occurring.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
><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 ...
}
CLASS="SECT3"
><A
NAME="S4"
->6.2.2. Use blocks for comments</A
+>4.2.2. Use blocks for comments</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Comments can help or they can clutter. They help when they
and the code. Block identifiers do, by surrounding the code
with a clear, definable pattern.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
>/*********************************************************************
* 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
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Exception:</I
+></SPAN
></P
><P
>If you are trying to add a small logic comment and do not
CLASS="SECT3"
><A
NAME="S5"
->6.2.3. Keep Comments on their own line</A
+>4.2.3. Keep Comments on their own line</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>It goes back to the question of readability. If the comment
at the end of closing braces, when used to comment
parameters.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
* 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
CLASS="SECT3"
><A
NAME="S6"
->6.2.4. Comment each logical step</A
+>4.2.4. Comment each logical step</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Logical steps should be commented to help others follow the
CLASS="SECT3"
><A
NAME="S7"
->6.2.5. Comment All Functions Thoroughly</A
+>4.2.5. Comment All Functions Thoroughly</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>A reader of the code should be able to look at the comments
CLASS="SECT3"
><A
NAME="S8"
->6.2.6. Comment at the end of braces if the
+>4.2.6. Comment at the end of braces if the
content is more than one screen length</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Each closing brace should be followed on the same line by a
>use following a closing brace: } /* -END- if() or while ()
or etc... */</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
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
CLASS="SECT2"
><A
NAME="S9"
->6.3. Naming Conventions</A
+>4.3. Naming Conventions</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S10"
->6.3.1. Variable Names</A
+>4.3.1. Variable Names</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Use all lowercase, and separate words via an underscore
template, class, true, false, ...). This is in case we ever
decide to port Privoxy to C++.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
><TABLE
CLASS="SECT3"
><A
NAME="S11"
->6.3.2. Function Names</A
+>4.3.2. Function Names</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Use all lowercase, and separate words via an underscore
template, class, true, false, ...). This is in case we ever
decide to port Privoxy to C++.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
><TABLE
CLASS="SECT3"
><A
NAME="S12"
->6.3.3. Header file prototypes</A
+>4.3.3. Header file prototypes</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Use a descriptive parameter name in the function prototype
in header files. Use the same parameter name in the header file
that you use in the c file.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
>
<TABLE
BORDER="0"
CLASS="SECT3"
><A
NAME="S13"
->6.3.4. Enumerations, and #defines</A
+>4.3.4. Enumerations, and #defines</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Use all capital letters, with underscores between words. Do
not start an identifier with an underscore. (ANSI C reserves
these for use by the compiler and system headers.)</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> We have a standard naming scheme for #defines
that toggle a feature in the preprocessor: FEATURE_>, where
> is a short (preferably 1 or 2 word) description.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="SECT3"
><A
NAME="S14"
->6.3.5. Constants</A
+>4.3.5. Constants</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Spell common words out entirely (do not remove vowels).</P
>Use underscore (_) to separate adjacent acronyms and
abbreviations. Never terminate a name with an underscore.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
><TABLE
CLASS="SECT2"
><A
NAME="S15"
->6.4. Using Space</A
+>4.4. Using Space</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S16"
->6.4.1. Put braces on a line by themselves.</A
+>4.4.1. Put braces on a line by themselves.</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>The brace needs to be on a line all by itself, not at the
easier to identify the opening and closing braces for a
block.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
>if ( this == that ) { ... }</P
><P
>if ( this == that ) { ... }</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> In the special case that the if-statement is
inside a loop, and it is trivial, i.e. it tests for a
condition that is obvious from the purpose of the block,
one-liners as above may optically preserve the loop structure
and make it easier to read.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> developer-discretion.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example exception:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="SECT3"
><A
NAME="S17"
->6.4.2. ALL control statements should have a
+>4.4.2. ALL control statements should have a
block</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Using braces to make a block will make your code more
readable and less prone to error. All control statements should
have a block defined.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="PROGRAMLISTING"
>if ( this == that )
{
- DoSomething();
- DoSomethingElse();
+ do_something();
+ do_something_else();
}</PRE
></TD
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></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"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> The first example in "Instead of" will execute
in a manner other than that which the developer desired (per
indentation). Using code braces would have prevented this
CLASS="SECT3"
><A
NAME="S18"
->6.4.3. Do not belabor/blow-up boolean
+>4.4.3. Do not belabor/blow-up boolean
expressions</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
>if ( condition ) { structure->flag = 1; } else {
structure->flag = 0; }</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> The former is readable and concise. The later
is wordy and inefficient. Please assume that any developer new
to the project has at least a "good" knowledge of C/C++. (Hope
CLASS="SECT3"
><A
NAME="S19"
->6.4.4. Use white space freely because it is
+>4.4.4. Use white space freely because it is
free</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Make it readable. The notable exception to using white space
freely is listed in the next guideline.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
><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
CLASS="SECT3"
><A
NAME="S20"
->6.4.5. Don't use white space around structure
+>4.4.5. Don't use white space around structure
operators</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>- structure pointer operator ( "->" ) - member operator (
connection between the object and variable/function name is not
as clear.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
><TD
><PRE
CLASS="PROGRAMLISTING"
->aStruct->aMember;
-aStruct.aMember;
-FunctionName();</PRE
+>a_struct->a_member;
+a_struct.a_member;
+function_name();</PRE
></TD
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
-> aStruct -> aMember; aStruct . aMember;
- FunctionName ();</P
+></SPAN
+> a_struct -> a_member; a_struct . a_member;
+ function_name ();</P
></DIV
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S21"
->6.4.6. Make the last brace of a function stand
+>4.4.6. Make the last brace of a function stand
out</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
>int function1( ... )
{
...code...
- return( retCode );
+ return( ret_code );
} /* -END- function1 */
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
->int function1( ... ) { ...code... return( retCode ); } int
+>int function1( ... ) { ...code... return( ret_code ); } int
function2( ... ) { }</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> Use 1 blank line before the closing brace and 2
lines afterward. This makes the end of function standout to
the most casual viewer. Although function comments help
"do" loops, and long if {} statements too. After all whitespace
is free!</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> developer-discretion on the number of blank
lines. Enforced is the end of function comments.</P
></DIV
CLASS="SECT3"
><A
NAME="S22"
->6.4.7. Use 3 character indentions</A
+>4.4.7. Use 3 character indentions</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>If some use 8 character TABs and some use 3 character TABs,
only. If you like to use TABs, pass your code through a filter
such as "expand -t3" before checking in your code.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="SECT2"
><A
NAME="S23"
->6.5. Initializing</A
+>4.5. Initializing</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S24"
->6.5.1. Initialize all variables</A
+>4.5.1. Initialize all variables</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Do not assume that the variables declared will not be used
the code. Remove the chance of accidentally using an unassigned
variable.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
><TD
><PRE
CLASS="PROGRAMLISTING"
->short anShort = 0;
-float aFloat = 0;
+>short a_short = 0;
+float a_float = 0;
struct *ptr = NULL;</PRE
></TD
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></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"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</P
></DIV
CLASS="SECT2"
><A
NAME="S25"
->6.6. Functions</A
+>4.6. Functions</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S26"
->6.6.1. Name functions that return a boolean as a
+>4.6.1. Name functions that return a boolean as a
question.</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Value should be phrased as a question that would logically
be answered as a true or false statement</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
><TD
><PRE
CLASS="PROGRAMLISTING"
->ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();</PRE
+>should_we_block_this();
+contains_an_image();
+is_web_page_blank();</PRE
></TD
></TR
></TABLE
CLASS="SECT3"
><A
NAME="S27"
->6.6.2. Always specify a return type for a
+>4.6.2. Always specify a return type for a
function.</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>The default return for a function is an int. To avoid
CLASS="SECT3"
><A
NAME="S28"
->6.6.3. Minimize function calls when iterating by
+>4.6.3. Minimize function calls when iterating by
using variables</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>It is easy to write the following code, and a clear argument
can be made that the code is easy to understand:</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
><TD
><PRE
CLASS="PROGRAMLISTING"
->for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+>for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
{
....
}</PRE
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> Unfortunately, this makes a function call for
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,
assign the value to a variable, and evaluate using the
variable.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
><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
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Exceptions:</I
-> if the value of blockListLength() *may*
- change or could *potentially* change, then you must code the
+></SPAN
+> 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
CLASS="SECT3"
><A
NAME="S29"
->6.6.4. Pass and Return by Const Reference</A
+>4.6.4. Pass and Return by Const Reference</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>This allows a developer to define a const pointer and call
CLASS="SECT3"
><A
NAME="S30"
->6.6.5. Pass and Return by Value</A
+>4.6.5. Pass and Return by Value</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Most structures cannot fit onto a normal stack entry (i.e.
CLASS="SECT3"
><A
NAME="S31"
->6.6.6. Names of include files</A
+>4.6.6. Names of include files</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Your include statements should contain the file name without
partial path to distinguish their header files from system or
other header files.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Exception:</I
+></SPAN
></P
><P
><TABLE
></TABLE
></P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
"file.h" behavior.</P
CLASS="SECT3"
><A
NAME="S32"
->6.6.7. Provide multiple inclusion
+>4.6.7. Provide multiple inclusion
protection</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Prevents compiler and linker errors resulting from
with your file name, with "." Changed to "_", and make it
uppercase.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="SECT3"
><A
NAME="S33"
->6.6.8. Use `extern "C"` when appropriate</A
+>4.6.8. Use `extern "C"` when appropriate</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>If our headers are included from C++, they must declare our
functions as `extern "C"`. This has no cost in C, but increases
the potential re-usability of our code.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="SECT3"
><A
NAME="S34"
->6.6.9. Where Possible, Use Forward Struct
+>4.6.9. Where Possible, Use Forward Struct
Declaration Instead of Includes</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Useful in headers that include pointers to other struct's.
Modifications to excess header files may cause needless
compiles.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> If you declare "file_list xyz;" (without the
pointer), then including the proper header file is necessary.
If you only want to prototype a pointer, however, the header
file is unnecessary.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> Use with discretion.</P
></DIV
></DIV
CLASS="SECT2"
><A
NAME="S35"
->6.7. General Coding Practices</A
+>4.7. General Coding Practices</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S36"
->6.7.1. Turn on warnings</A
+>4.7.1. Turn on warnings</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation</I
+></SPAN
></P
><P
>Compiler warnings are meant to help you find bugs. You
CLASS="SECT3"
><A
NAME="S37"
->6.7.2. Provide a default case for all switch
+>4.7.2. Provide a default case for all switch
statements</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>What you think is guaranteed is never really guaranteed. The
someday will be passed. So, to protect yourself from the
unknown, always have a default step in a switch statement.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> If you already have a default condition, you
are obviously exempt from this point. Of note, most of the
WIN32 code calls `DefWindowProc' after the switch statement.
This API call *should* be included in a default statement.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Another Note:</I
+></SPAN
> 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"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> Programmer discretion is advised.</P
></DIV
><DIV
CLASS="SECT3"
><A
NAME="S38"
->6.7.3. Try to avoid falling through cases in a
+>4.7.3. Try to avoid falling through cases in a
switch statement.</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>In general, you will want to have a 'break' statement within
CLASS="SECT3"
><A
NAME="S39"
->6.7.4. Use 'long' or 'short' Instead of
+>4.7.4. Use 'long' or 'short' Instead of
'int'</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>On 32-bit platforms, int usually has the range of long. On
16-bit platforms, int has the range of short.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> open-to-debate. In the case of most FSF
projects (including X/GNU-Emacs), there are typedefs to int4,
int8, int16, (or equivalence ... I forget the exact typedefs
CLASS="SECT3"
><A
NAME="S40"
->6.7.5. Don't mix size_t and other types</A
+>4.7.5. Don't mix size_t and other types</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>The type of size_t varies across platforms. Do not make
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"
CLASS="SECT3"
><A
NAME="S41"
->6.7.6. Declare each variable and struct on its
+>4.7.6. Declare each variable and struct on its
own line.</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>It can be tempting to declare a series of variables all on
one line. Don't.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
>long a, b, c;</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
> - there is more room for comments on the
individual variables - easier to add new variables without
messing up the original ones - when searching on a variable to
find its type, there is less clutter to "visually"
eliminate</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Exceptions:</I
+></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
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> developer-discretion.</P
></DIV
><DIV
CLASS="SECT3"
><A
NAME="S42"
->6.7.7. Use malloc/zalloc sparingly</A
+>4.7.7. Use malloc/zalloc sparingly</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Create a local struct (on the stack) if the variable will
>Only "malloc" a struct (on the heap) if the variable's life
will extend beyond the context of one function call.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="SECT3"
><A
NAME="S43"
->6.7.8. The Programmer Who Uses 'malloc' is
+>4.7.8. The Programmer Who Uses 'malloc' is
Responsible for Ensuring 'free'</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>If you have to "malloc" an instance, you are responsible for
responsible for ensuring that deletion is timely (i.e. not too
soon, not too late). This is known as "low-coupling" and is a
"good thing (tm)". You may need to offer a
- free/unload/destuctor type function to accommodate this.</P
+ free/unload/destructor type function to accommodate this.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Exceptions:</I
+></SPAN
></P
><P
>The developer cannot be expected to provide `free'ing
functions for C run-time library functions ... such as
`strdup'.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).</P
CLASS="SECT3"
><A
NAME="S44"
->6.7.9. Add loaders to the `file_list' structure
+>4.7.9. Add loaders to the `file_list' structure
and in order</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>I have ordered all of the "blocker" file code to be in alpha
order. It is easier to add/read new blockers when you expect a
certain order.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> It may appear that the alpha order is broken in
places by POPUP tests coming before PCRS tests. But since
POPUPs can also be referred to as KILLPOPUPs, it is clear that
CLASS="SECT3"
><A
NAME="S45"
->6.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME</A
+>4.7.10. "Uncertain" new code and/or changes to
+ existing code, use FIXME or XXX</A
></H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>If you have enough confidence in new code or confidence in
>/* FIXME: new code that *may* break something else... */
...new code here...</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> If you make it clear that this may or may not
be a "good thing (tm)", it will be easier to identify and
include in the project (or conversely exclude from the
CLASS="SECT2"
><A
NAME="S46"
->6.8. Addendum: Template for files and function
+>4.8. Addendum: Template for files and function
comment blocks:</A
></H2
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example for file comments:</I
+></SPAN
></P
><TABLE
BORDER="0"
><TD
><PRE
CLASS="PROGRAMLISTING"
->const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.35 2002/04/17 15:16:15 oes Exp $";
+>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.20 2008/06/14 13:21:24 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
* 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$
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> This declares the rcs variables that should be
added to the "show-proxy-args" page. If this is a brand new
creation by you, you are free to change the "Copyright" section
to represent the rights you wish to maintain.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> The formfeed character that is present right
after the comment flower box is handy for (X|GNU)Emacs users to
skip the verbiage and get to the heart of the code (via
`forward-page' and `backward-page'). Please include it if you
can.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example for file header comments:</I
+></SPAN
></P
><TABLE
BORDER="0"
CLASS="PROGRAMLISTING"
>#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.35 2002/04/17 15:16:15 oes Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.20 2008/06/14 13:21:24 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
* 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$
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Example for function comments:</I
+></SPAN
></P
><TABLE
BORDER="0"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Note:</I
+></SPAN
> If we all follow this practice, we should be
able to parse our code to create a "self-documenting" web
page.</P
><HR
ALIGN="LEFT"
WIDTH="100%"><TABLE
+SUMMARY="Footer navigation table"
WIDTH="100%"
BORDER="0"
CELLPADDING="0"
VALIGN="top"
><A
HREF="documentation.html"
+ACCESSKEY="P"
>Prev</A
></TD
><TD
VALIGN="top"
><A
HREF="index.html"
+ACCESSKEY="H"
>Home</A
></TD
><TD
VALIGN="top"
><A
HREF="testing.html"
+ACCESSKEY="N"
>Next</A
></TD
></TR
projects / privoxy.git / blobdiff