>Coding Guidelines</TITLE
><META
NAME="GENERATOR"
-CONTENT="Modular DocBook HTML Stylesheet Version 1.64
+CONTENT="Modular DocBook HTML Stylesheet Version 1.76b+
"><LINK
REL="HOME"
TITLE="Privoxy Developer Manual"
><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
><H1
CLASS="SECT1"
><A
-NAME="CODING"
->4. Coding Guidelines</A
-></H1
+NAME="CODING">4. Coding Guidelines</H1
><DIV
CLASS="SECT2"
><H2
CLASS="SECT2"
><A
-NAME="S1"
->4.1. Introduction</A
-></H2
+NAME="S1">4.1. Introduction</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</A
-></H2
+NAME="S2">4.2. Using Comments</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S3"
->4.2.1. Comment, Comment, Comment</A
-></H3
+NAME="S3">4.2.1. Comment, Comment, Comment</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Comment as much as possible without commenting the obvious.
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"
><H3
CLASS="SECT3"
><A
-NAME="S4"
->4.2.2. Use blocks for comments</A
-></H3
+NAME="S4">4.2.2. Use blocks for comments</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"
></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
><H3
CLASS="SECT3"
><A
-NAME="S5"
->4.2.3. Keep Comments on their own line</A
-></H3
+NAME="S5">4.2.3. Keep Comments on their own line</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"
><H3
CLASS="SECT3"
><A
-NAME="S6"
->4.2.4. Comment each logical step</A
-></H3
+NAME="S6">4.2.4. Comment each logical step</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Logical steps should be commented to help others follow the
><H3
CLASS="SECT3"
><A
-NAME="S7"
->4.2.5. Comment All Functions Thoroughly</A
-></H3
+NAME="S7">4.2.5. Comment All Functions Thoroughly</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
><H3
CLASS="SECT3"
><A
-NAME="S8"
->4.2.6. Comment at the end of braces if the
- content is more than one screen length</A
-></H3
+NAME="S8">4.2.6. Comment at the end of braces if the
+ content is more than one screen length</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"
><H2
CLASS="SECT2"
><A
-NAME="S9"
->4.3. Naming Conventions</A
-></H2
+NAME="S9">4.3. Naming Conventions</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S10"
->4.3.1. Variable Names</A
-></H3
+NAME="S10">4.3.1. Variable Names</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
><H3
CLASS="SECT3"
><A
-NAME="S11"
->4.3.2. Function Names</A
-></H3
+NAME="S11">4.3.2. Function Names</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
><H3
CLASS="SECT3"
><A
-NAME="S12"
->4.3.3. Header file prototypes</A
-></H3
+NAME="S12">4.3.3. Header file prototypes</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"
><H3
CLASS="SECT3"
><A
-NAME="S13"
->4.3.4. Enumerations, and #defines</A
-></H3
+NAME="S13">4.3.4. Enumerations, and #defines</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"
><H3
CLASS="SECT3"
><A
-NAME="S14"
->4.3.5. Constants</A
-></H3
+NAME="S14">4.3.5. Constants</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
><H2
CLASS="SECT2"
><A
-NAME="S15"
->4.4. Using Space</A
-></H2
+NAME="S15">4.4. Using Space</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S16"
->4.4.1. Put braces on a line by themselves.</A
-></H3
+NAME="S16">4.4.1. Put braces on a line by themselves.</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"
><H3
CLASS="SECT3"
><A
-NAME="S17"
->4.4.2. ALL control statements should have a
- block</A
-></H3
+NAME="S17">4.4.2. ALL control statements should have a
+ block</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"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
></P
><P
>if ( this == that ) DoSomething(); DoSomethingElse();</P
><P
>if ( this == that ) DoSomething();</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
><H3
CLASS="SECT3"
><A
-NAME="S18"
->4.4.3. Do not belabor/blow-up boolean
- expressions</A
-></H3
+NAME="S18">4.4.3. Do not belabor/blow-up boolean
+ expressions</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
><H3
CLASS="SECT3"
><A
-NAME="S19"
->4.4.4. Use white space freely because it is
- free</A
-></H3
+NAME="S19">4.4.4. Use white space freely because it is
+ free</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"
><H3
CLASS="SECT3"
><A
-NAME="S20"
->4.4.5. Don't use white space around structure
- operators</A
-></H3
+NAME="S20">4.4.5. Don't use white space around structure
+ operators</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"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Instead of:</I
+></SPAN
> aStruct -> aMember; aStruct . aMember;
FunctionName ();</P
></DIV
><H3
CLASS="SECT3"
><A
-NAME="S21"
->4.4.6. Make the last brace of a function stand
- out</A
-></H3
+NAME="S21">4.4.6. Make the last brace of a function stand
+ out</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
>int function1( ... ) { ...code... return( retCode ); } 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
><H3
CLASS="SECT3"
><A
-NAME="S22"
->4.4.7. Use 3 character indentions</A
-></H3
+NAME="S22">4.4.7. Use 3 character indentions</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"
><H2
CLASS="SECT2"
><A
-NAME="S23"
->4.5. Initializing</A
-></H2
+NAME="S23">4.5. Initializing</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S24"
->4.5.1. Initialize all variables</A
-></H3
+NAME="S24">4.5.1. Initialize all variables</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"
></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
><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
><H2
CLASS="SECT2"
><A
-NAME="S25"
->4.6. Functions</A
-></H2
+NAME="S25">4.6. Functions</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S26"
->4.6.1. Name functions that return a boolean as a
- question.</A
-></H3
+NAME="S26">4.6.1. Name functions that return a boolean as a
+ question.</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"
><H3
CLASS="SECT3"
><A
-NAME="S27"
->4.6.2. Always specify a return type for a
- function.</A
-></H3
+NAME="S27">4.6.2. Always specify a return type for a
+ function.</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>The default return for a function is an int. To avoid
><H3
CLASS="SECT3"
><A
-NAME="S28"
->4.6.3. Minimize function calls when iterating by
- using variables</A
-></H3
+NAME="S28">4.6.3. Minimize function calls when iterating by
+ using variables</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"
></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
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"
></TR
></TABLE
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Exceptions:</I
+></SPAN
> if the value of blockListLength() *may*
change or could *potentially* change, then you must code the
function call in the for/while loop.</P
><H3
CLASS="SECT3"
><A
-NAME="S29"
->4.6.4. Pass and Return by Const Reference</A
-></H3
+NAME="S29">4.6.4. Pass and Return by Const Reference</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>This allows a developer to define a const pointer and call
><H3
CLASS="SECT3"
><A
-NAME="S30"
->4.6.5. Pass and Return by Value</A
-></H3
+NAME="S30">4.6.5. Pass and Return by Value</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>Most structures cannot fit onto a normal stack entry (i.e.
><H3
CLASS="SECT3"
><A
-NAME="S31"
->4.6.6. Names of include files</A
-></H3
+NAME="S31">4.6.6. Names of include files</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
><H3
CLASS="SECT3"
><A
-NAME="S32"
->4.6.7. Provide multiple inclusion
- protection</A
-></H3
+NAME="S32">4.6.7. Provide multiple inclusion
+ protection</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"
><H3
CLASS="SECT3"
><A
-NAME="S33"
->4.6.8. Use `extern "C"` when appropriate</A
-></H3
+NAME="S33">4.6.8. Use `extern "C"` when appropriate</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"
><H3
CLASS="SECT3"
><A
-NAME="S34"
->4.6.9. Where Possible, Use Forward Struct
- Declaration Instead of Includes</A
-></H3
+NAME="S34">4.6.9. Where Possible, Use Forward Struct
+ Declaration Instead of Includes</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
><H2
CLASS="SECT2"
><A
-NAME="S35"
->4.7. General Coding Practices</A
-></H2
+NAME="S35">4.7. General Coding Practices</H2
><DIV
CLASS="SECT3"
><H3
CLASS="SECT3"
><A
-NAME="S36"
->4.7.1. Turn on warnings</A
-></H3
+NAME="S36">4.7.1. Turn on warnings</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation</I
+></SPAN
></P
><P
>Compiler warnings are meant to help you find bugs. You
><H3
CLASS="SECT3"
><A
-NAME="S37"
->4.7.2. Provide a default case for all switch
- statements</A
-></H3
+NAME="S37">4.7.2. Provide a default case for all switch
+ statements</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
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> Programmer discretion is advised.</P
></DIV
><DIV
><H3
CLASS="SECT3"
><A
-NAME="S38"
->4.7.3. Try to avoid falling through cases in a
- switch statement.</A
-></H3
+NAME="S38">4.7.3. Try to avoid falling through cases in a
+ switch statement.</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>In general, you will want to have a 'break' statement within
><H3
CLASS="SECT3"
><A
-NAME="S39"
->4.7.4. Use 'long' or 'short' Instead of
- 'int'</A
-></H3
+NAME="S39">4.7.4. Use 'long' or 'short' Instead of
+ 'int'</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
><H3
CLASS="SECT3"
><A
-NAME="S40"
->4.7.5. Don't mix size_t and other types</A
-></H3
+NAME="S40">4.7.5. Don't mix size_t and other types</H3
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Explanation:</I
+></SPAN
></P
><P
>The type of size_t varies across platforms. Do not make
><H3
CLASS="SECT3"
><A
-NAME="S41"
->4.7.6. Declare each variable and struct on its
- own line.</A
-></H3
+NAME="S41">4.7.6. Declare each variable and struct on its
+ own line.</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
their functions.</P
><P
+><SPAN
+CLASS="emphasis"
><I
CLASS="EMPHASIS"
>Status:</I
+></SPAN
> developer-discretion.</P
></DIV
><DIV
><H3
CLASS="SECT3"
><A
-NAME="S42"
->4.7.7. Use malloc/zalloc sparingly</A
-></H3
+NAME="S42">4.7.7. Use malloc/zalloc sparingly</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"
><H3
CLASS="SECT3"
><A
-NAME="S43"
->4.7.8. The Programmer Who Uses 'malloc' is
- Responsible for Ensuring 'free'</A
-></H3
+NAME="S43">4.7.8. The Programmer Who Uses 'malloc' is
+ Responsible for Ensuring 'free'</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
><H3
CLASS="SECT3"
><A
-NAME="S44"
->4.7.9. Add loaders to the `file_list' structure
- and in order</A
-></H3
+NAME="S44">4.7.9. Add loaders to the `file_list' structure
+ and in order</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
><H3
CLASS="SECT3"
><A
-NAME="S45"
->4.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME</A
-></H3
+NAME="S45">4.7.10. "Uncertain" new code and/or changes to
+ existing code, use FIXME</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
><H2
CLASS="SECT2"
><A
-NAME="S46"
->4.8. Addendum: Template for files and function
- comment blocks:</A
-></H2
+NAME="S46">4.8. Addendum: Template for files and function
+ comment blocks:</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.45 2002/05/19 23:01:54 hal9 Exp $";
+>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.3 2002/09/05 02:27:59 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
></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.45 2002/05/19 23:01:54 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.3 2002/09/05 02:27:59 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
></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