1578 lines
51 KiB
HTML
1578 lines
51 KiB
HTML
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"
|
|
"http://www.w3.org/TR/html4/loose.dtd">
|
|
|
|
<html>
|
|
<head>
|
|
<meta name="generator" content=
|
|
"HTML Tidy for Linux/x86 (vers 7 December 2008), see www.w3.org">
|
|
|
|
<title>Coding Guidelines</title>
|
|
<meta name="GENERATOR" content=
|
|
"Modular DocBook HTML Stylesheet Version 1.79">
|
|
<link rel="HOME" title="Privoxy Developer Manual" href="index.html">
|
|
<link rel="PREVIOUS" title="Documentation Guidelines" href=
|
|
"documentation.html">
|
|
<link rel="NEXT" title="Testing Guidelines" href="testing.html">
|
|
<link rel="STYLESHEET" type="text/css" href="../p_doc.css">
|
|
<meta http-equiv="Content-Type" content="text/html; charset=us-ascii">
|
|
<style type="text/css">
|
|
body {
|
|
background-color: #EEEEEE;
|
|
color: #000000;
|
|
}
|
|
:link { color: #0000FF }
|
|
:visited { color: #840084 }
|
|
:active { color: #0000FF }
|
|
table.c3 {background-color: #E0E0E0}
|
|
span.c2 {font-style: italic}
|
|
hr.c1 {text-align: left}
|
|
</style>
|
|
</head>
|
|
|
|
<body class="SECT1">
|
|
<div class="NAVHEADER">
|
|
<table summary="Header navigation table" width="100%" border="0"
|
|
cellpadding="0" cellspacing="0">
|
|
<tr>
|
|
<th colspan="3" align="center">Privoxy Developer Manual</th>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td width="10%" align="left" valign="bottom"><a href=
|
|
"documentation.html" accesskey="P">Prev</a></td>
|
|
|
|
<td width="80%" align="center" valign="bottom"></td>
|
|
|
|
<td width="10%" align="right" valign="bottom"><a href="testing.html"
|
|
accesskey="N">Next</a></td>
|
|
</tr>
|
|
</table>
|
|
<hr class="c1" width="100%">
|
|
</div>
|
|
|
|
<div class="SECT1">
|
|
<h1 class="SECT1"><a name="CODING" id="CODING">4. Coding
|
|
Guidelines</a></h1>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S1" id="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
|
|
<span class="APPLICATION">Privoxy</span>" consistent and reliable. Thus
|
|
making maintenance easier and increasing chances of success of the
|
|
project.</p>
|
|
|
|
<p>And that of course comes back to us as individuals. If we can
|
|
increase our development and product efficiencies then we can solve
|
|
more of the request for changes/improvements and in general feel good
|
|
about ourselves. ;-></p>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S2" id="S2">4.2. Using Comments</a></h2>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S3" id="S3">4.2.1. Comment, Comment,
|
|
Comment</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Comment as much as possible without commenting the obvious. 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 or explanation would have
|
|
prevented the extra research. Please help your brother IJB'ers
|
|
out!</p>
|
|
|
|
<p>The comments will also help justify the intent of the code. If the
|
|
comment describes something different than what the code is doing
|
|
then maybe a programming error is occurring.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
/* if page size greater than 1k ... */
|
|
if ( page_length() > 1024 )
|
|
{
|
|
... "block" the page up ...
|
|
}
|
|
|
|
/* if page size is small, send it in blocks */
|
|
if ( page_length() > 1024 )
|
|
{
|
|
... "block" the page up ...
|
|
}
|
|
|
|
This demonstrates 2 cases of "what not to do". The first is a
|
|
"syntax comment". The second is a comment that does not fit what
|
|
is actually being done.
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S4" id="S4">4.2.2. Use blocks for
|
|
comments</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Comments can help or they can clutter. They help when they are
|
|
differentiated from the code they describe. One line comments do not
|
|
offer effective separation between the comment and the code. Block
|
|
identifiers do, by surrounding the code with a clear, definable
|
|
pattern.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
/*********************************************************************
|
|
* This will stand out clearly in your code!
|
|
*********************************************************************/
|
|
if ( this_variable == that_variable )
|
|
{
|
|
do_something_very_important();
|
|
}
|
|
|
|
|
|
/* unfortunately, this may not */
|
|
if ( this_variable == that_variable )
|
|
{
|
|
do_something_very_important();
|
|
}
|
|
|
|
|
|
if ( this_variable == that_variable ) /* this may not either */
|
|
{
|
|
do_something_very_important();
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Exception:</span></p>
|
|
|
|
<p>If you are trying to add a small logic comment and do not wish to
|
|
"disrupt" the flow of the code, feel free to use a 1 line comment
|
|
which is NOT on the same line as the code.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S5" id="S5">4.2.3. Keep Comments on their
|
|
own line</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>It goes back to the question of readability. If the comment is on
|
|
the same line as the code it will be harder to read than the comment
|
|
that is on its own line.</p>
|
|
|
|
<p>There are three exceptions to this rule, which should be violated
|
|
freely and often: during the definition of variables, at the end of
|
|
closing braces, when used to comment parameters.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
/*********************************************************************
|
|
* This will stand out clearly in your code,
|
|
* But the second example won't.
|
|
*********************************************************************/
|
|
if ( this_variable == this_variable )
|
|
{
|
|
do_something_very_important();
|
|
}
|
|
|
|
if ( this_variable == this_variable ) /*can you see me?*/
|
|
{
|
|
do_something_very_important(); /*not easily*/
|
|
}
|
|
|
|
|
|
/*********************************************************************
|
|
* But, the encouraged exceptions:
|
|
*********************************************************************/
|
|
int urls_read = 0; /* # of urls read + rejected */
|
|
int urls_rejected = 0; /* # of urls rejected */
|
|
|
|
if ( 1 == X )
|
|
{
|
|
do_something_very_important();
|
|
}
|
|
|
|
|
|
short do_something_very_important(
|
|
short firstparam, /* represents something */
|
|
short nextparam /* represents something else */ )
|
|
{
|
|
...code here...
|
|
|
|
} /* -END- do_something_very_important */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S6" id="S6">4.2.4. Comment each logical
|
|
step</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Logical steps should be commented to help others follow the intent
|
|
of the written code and comments will make the code more
|
|
readable.</p>
|
|
|
|
<p>If you have 25 lines of code without a comment, you should
|
|
probably go back into it to see where you forgot to put one.</p>
|
|
|
|
<p>Most "for", "while", "do", etc... loops _probably_ need a comment.
|
|
After all, these are usually major logic containers.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S7" id="S7">4.2.5. Comment All Functions
|
|
Thoroughly</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>A reader of the code should be able to look at the comments just
|
|
prior to the beginning of a function and discern the reason for its
|
|
existence and the consequences of using it. The reader should not
|
|
have to read through the code to determine if a given function is
|
|
safe for a desired use. The proper information thoroughly presented
|
|
at the introduction of a function not only saves time for subsequent
|
|
maintenance or debugging, it more importantly aids in code reuse by
|
|
allowing a user to determine the safety and applicability of any
|
|
function for the problem at hand. As a result of such benefits, all
|
|
functions should contain the information presented in the addendum
|
|
section of this document.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S8" id="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 EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Each closing brace should be followed on the same line by a
|
|
comment that describes the origination of the brace if the original
|
|
brace is off of the screen, or otherwise far away from the closing
|
|
brace. This will simplify the debugging, maintenance, and readability
|
|
of the code.</p>
|
|
|
|
<p>As a suggestion , use the following flags to make the comment and
|
|
its brace more readable:</p>
|
|
|
|
<p>use following a closing brace: } /* -END- if() or while () or
|
|
etc... */</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
if ( 1 == X )
|
|
{
|
|
do_something_very_important();
|
|
...some long list of commands...
|
|
} /* -END- if x is 1 */
|
|
|
|
or:
|
|
|
|
if ( 1 == X )
|
|
{
|
|
do_something_very_important();
|
|
...some long list of commands...
|
|
} /* -END- if ( 1 == X ) */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S9" id="S9">4.3. Naming Conventions</a></h2>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S10" id="S10">4.3.1. Variable
|
|
Names</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Use all lowercase, and separate words via an underscore ('_'). Do
|
|
not start an identifier with an underscore. (ANSI C reserves these
|
|
for use by the compiler and system headers.) Do not use identifiers
|
|
which are reserved in ANSI C++. (E.g. template, class, true, false,
|
|
...). This is in case we ever decide to port Privoxy to C++.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
int ms_iis5_hack = 0;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
int msiis5hack = 0; int msIis5Hack = 0;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S11" id="S11">4.3.2. Function
|
|
Names</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Use all lowercase, and separate words via an underscore ('_'). Do
|
|
not start an identifier with an underscore. (ANSI C reserves these
|
|
for use by the compiler and system headers.) Do not use identifiers
|
|
which are reserved in ANSI C++. (E.g. template, class, true, false,
|
|
...). This is in case we ever decide to port Privoxy to C++.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
int load_some_file( struct client_state *csp )
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
int loadsomefile( struct client_state *csp )
|
|
int loadSomeFile( struct client_state *csp )
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S12" id="S12">4.3.3. Header file
|
|
prototypes</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
(.h) extern int load_aclfile( struct client_state *csp );
|
|
(.c) int load_aclfile( struct client_state *csp )
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
(.h) extern int load_aclfile( struct client_state * ); or
|
|
(.h) extern int load_aclfile();
|
|
(.c) int load_aclfile( struct client_state *csp )
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S13" id="S13">4.3.4. Enumerations, and
|
|
#defines</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
(enumeration) : enum Boolean { FALSE, TRUE };
|
|
(#define) : #define DEFAULT_SIZE 100;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
#define FEATURE_FORCE 1
|
|
|
|
#ifdef FEATURE_FORCE
|
|
#define FORCE_PREFIX blah
|
|
#endif /* def FEATURE_FORCE */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S14" id="S14">4.3.5. Constants</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Spell common words out entirely (do not remove vowels).</p>
|
|
|
|
<p>Use only widely-known domain acronyms and abbreviations.
|
|
Capitalize all letters of an acronym.</p>
|
|
|
|
<p>Use underscore (_) to separate adjacent acronyms and
|
|
abbreviations. Never terminate a name with an underscore.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
#define USE_IMAGE_LIST 1
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
#define USE_IMG_LST 1 or
|
|
#define _USE_IMAGE_LIST 1 or
|
|
#define USE_IMAGE_LIST_ 1 or
|
|
#define use_image_list 1 or
|
|
#define UseImageList 1
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S15" id="S15">4.4. Using Space</a></h2>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S16" id="S16">4.4.1. Put braces on a line
|
|
by themselves.</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>The brace needs to be on a line all by itself, not at the end of
|
|
the statement. Curly braces should line up with the construct that
|
|
they're associated with. This practice makes it easier to identify
|
|
the opening and closing braces for a block.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
if ( this == that )
|
|
{
|
|
...
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<p>if ( this == that ) { ... }</p>
|
|
|
|
<p>or</p>
|
|
|
|
<p>if ( this == that ) { ... }</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 EMPHASIS c2">Status:</span>
|
|
developer-discretion.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example exception:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
while ( more lines are read )
|
|
{
|
|
/* Please document what is/is not a comment line here */
|
|
if ( it's a comment ) continue;
|
|
|
|
do_something( line );
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S17" id="S17">4.4.2. ALL control
|
|
statements should have a block</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
if ( this == that )
|
|
{
|
|
do_something();
|
|
do_something_else();
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<p>if ( this == that ) do_something(); do_something_else();</p>
|
|
|
|
<p>or</p>
|
|
|
|
<p>if ( this == that ) do_something();</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 "feature". The "explanation" and "exception" from the
|
|
point above also applies.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S18" id="S18">4.4.3. Do not
|
|
belabor/blow-up boolean expressions</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
structure->flag = ( condition );
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<p>if ( condition ) { structure->flag = 1; } else {
|
|
structure->flag = 0; }</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 I do not offend by that last comment ...
|
|
8-)</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S19" id="S19">4.4.4. Use white space
|
|
freely because it is free</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
int first_value = 0;
|
|
int some_value = 0;
|
|
int another_value = 0;
|
|
int this_variable = 0;
|
|
|
|
if ( this_variable == this_variable )
|
|
|
|
first_value = old_value + ( ( some_value - another_value ) - whatever )
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S20" id="S20">4.4.5. Don't use white space
|
|
around structure operators</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>- structure pointer operator ( "->" ) - member operator ( "." )
|
|
- functions and parentheses</p>
|
|
|
|
<p>It is a general coding practice to put pointers, references, and
|
|
function parentheses next to names. With spaces, the connection
|
|
between the object and variable/function name is not as clear.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
a_struct->a_member;
|
|
a_struct.a_member;
|
|
function_name();
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span> a_struct
|
|
-> a_member; a_struct . a_member; function_name ();</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S21" id="S21">4.4.6. Make the last brace
|
|
of a function stand out</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
int function1( ... )
|
|
{
|
|
...code...
|
|
return( ret_code );
|
|
|
|
} /* -END- function1 */
|
|
|
|
|
|
int function2( ... )
|
|
{
|
|
} /* -END- function2 */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<p>int function1( ... ) { ...code... return( ret_code ); } int
|
|
function2( ... ) { }</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 separate functions, this is still a good coding
|
|
practice. In fact, I follow these rules when using blocks in "for",
|
|
"while", "do" loops, and long if {} statements too. After all
|
|
whitespace is free!</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Status:</span>
|
|
developer-discretion on the number of blank lines. Enforced is the
|
|
end of function comments.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S22" id="S22">4.4.7. Use 3 character
|
|
indentions</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>If some use 8 character TABs and some use 3 character TABs, the
|
|
code can look *very* ragged. So use 3 character indentions 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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
static const char * const url_code_map[256] =
|
|
{
|
|
NULL, ...
|
|
};
|
|
|
|
|
|
int function1( ... )
|
|
{
|
|
if ( 1 )
|
|
{
|
|
return( ALWAYS_TRUE );
|
|
}
|
|
else
|
|
{
|
|
return( HOW_DID_YOU_GET_HERE );
|
|
}
|
|
|
|
return( NEVER_GETS_HERE );
|
|
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S23" id="S23">4.5. Initializing</a></h2>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S24" id="S24">4.5.1. Initialize all
|
|
variables</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Do not assume that the variables declared will not be used until
|
|
after they have been assigned a value somewhere else in the code.
|
|
Remove the chance of accidentally using an unassigned variable.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
short a_short = 0;
|
|
float a_float = 0;
|
|
struct *ptr = NULL;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 array_ptr[20] causes a
|
|
SIGSEV vs. array_ptr[0].</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Status:</span>
|
|
developer-discretion if and only if the variable is assigned a value
|
|
"shortly after" declaration.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S25" id="S25">4.6. Functions</a></h2>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S26" id="S26">4.6.1. Name functions that
|
|
return a boolean as a question.</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
should_we_block_this();
|
|
contains_an_image();
|
|
is_web_page_blank();
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S27" id="S27">4.6.2. Always specify a
|
|
return type for a function.</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>The default return for a function is an int. To avoid ambiguity,
|
|
create a return for a function when the return has a purpose, and
|
|
create a void return type if the function does not need to return
|
|
anything.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S28" id="S28">4.6.3. Minimize function
|
|
calls when iterating by using variables</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
for ( size_t cnt = 0; cnt < block_list_length(); cnt++ )
|
|
{
|
|
....
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 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 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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
size_t len = block_list_length();
|
|
|
|
for ( size_t cnt = 0; cnt < len; cnt++ )
|
|
{
|
|
....
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Exceptions:</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">
|
|
<h3 class="SECT3"><a name="S29" id="S29">4.6.4. Pass and Return by
|
|
Const Reference</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>This allows a developer to define a const pointer and call your
|
|
function. If your function does not have the const keyword, we may
|
|
not be able to use your function. Consider strcmp, if it were defined
|
|
as: extern int strcmp( char *s1, char *s2 );</p>
|
|
|
|
<p>I could then not use it to compare argv's in main: int main( int
|
|
argc, const char *argv[] ) { strcmp( argv[0], "privoxy" ); }</p>
|
|
|
|
<p>Both these pointers are *const*! If the c runtime library
|
|
maintainers do it, we should too.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S30" id="S30">4.6.5. Pass and Return by
|
|
Value</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Most structures cannot fit onto a normal stack entry (i.e. they
|
|
are not 4 bytes or less). Aka, a function declaration like: int
|
|
load_aclfile( struct client_state csp )</p>
|
|
|
|
<p>would not work. So, to be consistent, we should declare all
|
|
prototypes with "pass by value": int load_aclfile( struct
|
|
client_state *csp )</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S31" id="S31">4.6.6. Names of include
|
|
files</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Your include statements should contain the file name without a
|
|
path. The path should be listed in the Makefile, using -I as
|
|
processor directive to search the indicated paths. An exception to
|
|
this would be for some proprietary software that utilizes a partial
|
|
path to distinguish their header files from system or other header
|
|
files.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
#include <iostream.h> /* This is not a local include */
|
|
#include "config.h" /* This IS a local include */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Exception:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
/* This is not a local include, but requires a path element. */
|
|
#include <sys/fileName.h>
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</span> Please! do not add
|
|
"-I." to the Makefile without a _very_ good reason. This duplicates
|
|
the #include "file.h" behavior.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S32" id="S32">4.6.7. Provide multiple
|
|
inclusion protection</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Prevents compiler and linker errors resulting from redefinition of
|
|
items.</p>
|
|
|
|
<p>Wrap each header file with the following syntax to prevent
|
|
multiple inclusions of the file. Of course, replace PROJECT_H with
|
|
your file name, with "." Changed to "_", and make it uppercase.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
#ifndef PROJECT_H_INCLUDED
|
|
#define PROJECT_H_INCLUDED
|
|
...
|
|
#endif /* ndef PROJECT_H_INCLUDED */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S33" id="S33">4.6.8. Use `extern "C"` when
|
|
appropriate</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
#ifdef __cplusplus
|
|
extern "C"
|
|
{
|
|
#endif /* def __cplusplus */
|
|
|
|
... function definitions here ...
|
|
|
|
#ifdef __cplusplus
|
|
}
|
|
#endif /* def __cplusplus */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S34" id="S34">4.6.9. Where Possible, Use
|
|
Forward Struct Declaration Instead of Includes</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
/*********************************************************************
|
|
* We're avoiding an include statement here!
|
|
*********************************************************************/
|
|
struct file_list;
|
|
extern file_list *xyz;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 EMPHASIS c2">Status:</span> Use with
|
|
discretion.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S35" id="S35">4.7. General Coding
|
|
Practices</a></h2>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S36" id="S36">4.7.1. Turn on
|
|
warnings</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation</span></p>
|
|
|
|
<p>Compiler warnings are meant to help you find bugs. You should turn
|
|
on as many as possible. With GCC, the switch is "-Wall". Try and fix
|
|
as many warnings as possible.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S37" id="S37">4.7.2. Provide a default
|
|
case for all switch statements</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>What you think is guaranteed is never really guaranteed. The value
|
|
that you don't think you need to check is the one that 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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
switch( hash_string( cmd ) )
|
|
{
|
|
case hash_actions_file :
|
|
... code ...
|
|
break;
|
|
|
|
case hash_confdir :
|
|
... code ...
|
|
break;
|
|
|
|
default :
|
|
log_error( ... );
|
|
... anomaly code goes here ...
|
|
continue; / break; / exit( 1 ); / etc ...
|
|
|
|
} /* end switch( hash_string( cmd ) ) */
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 EMPHASIS c2">Another Note:</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 abort
|
|
condition.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Status:</span> Programmer
|
|
discretion is advised.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S38" id="S38">4.7.3. Try to avoid falling
|
|
through cases in a switch statement.</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>In general, you will want to have a 'break' statement within each
|
|
'case' of a switch statement. This allows for the code to be more
|
|
readable and understandable, and furthermore can prevent unwanted
|
|
surprises if someone else later gets creative and moves the code
|
|
around.</p>
|
|
|
|
<p>The language allows you to plan the fall through from one case
|
|
statement to another simply by omitting the break statement within
|
|
the case statement. This feature does have benefits, but should only
|
|
be used in rare cases. In general, use a break statement for each
|
|
case statement.</p>
|
|
|
|
<p>If you choose to allow fall through, you should comment both the
|
|
fact of the fall through and reason why you felt it was
|
|
necessary.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S39" id="S39">4.7.4. Use 'long' or 'short'
|
|
Instead of 'int'</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Status:</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 now). Should we add these to IJB now that we have a
|
|
"configure" script?</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S40" id="S40">4.7.5. Don't mix size_t and
|
|
other types</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S41" id="S41">4.7.6. Declare each variable
|
|
and struct on its own line.</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>It can be tempting to declare a series of variables all on one
|
|
line. Don't.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
long a = 0;
|
|
long b = 0;
|
|
long c = 0;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Instead of:</span></p>
|
|
|
|
<p>long a, b, c;</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Exceptions:</span> when you
|
|
want to declare a bunch of loop variables or other trivial variables;
|
|
feel free to declare them on one line. You should, although, provide
|
|
a good comment on their functions.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Status:</span>
|
|
developer-discretion.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S42" id="S42">4.7.7. Use malloc/zalloc
|
|
sparingly</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>Create a local struct (on the stack) if the variable will live and
|
|
die within the context of one function call.</p>
|
|
|
|
<p>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 EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
If a function creates a struct and stores a pointer to it in a
|
|
list, then it should definitely be allocated via `malloc'.
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S43" id="S43">4.7.8. The Programmer Who
|
|
Uses 'malloc' is Responsible for Ensuring 'free'</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>If you have to "malloc" an instance, you are responsible for
|
|
insuring that the instance is `free'd, even if the deallocation event
|
|
falls within some other programmer's code. You are also 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/destructor type function to
|
|
accommodate this.</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
int load_re_filterfile( struct client_state *csp ) { ... }
|
|
static void unload_re_filterfile( void *f ) { ... }
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Exceptions:</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 EMPHASIS c2">Status:</span>
|
|
developer-discretion. The "main" use of this standard is for
|
|
allocating and freeing data structures (complex or nested).</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S44" id="S44">4.7.9. Add loaders to the
|
|
`file_list' structure and in order</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</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 EMPHASIS c2">Note:</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 it should come first.</p>
|
|
</div>
|
|
|
|
<div class="SECT3">
|
|
<h3 class="SECT3"><a name="S45" id="S45">4.7.10. "Uncertain" new code
|
|
and/or changes to existing code, use FIXME or XXX</a></h3>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Explanation:</span></p>
|
|
|
|
<p>If you have enough confidence in new code or confidence in your
|
|
changes, but are not *quite* sure of the repercussions, add this:</p>
|
|
|
|
<p>/* FIXME: this code has a logic error on platform XYZ, *
|
|
attempting to fix */ #ifdef PLATFORM ...changed code here...
|
|
#endif</p>
|
|
|
|
<p>or:</p>
|
|
|
|
<p>/* FIXME: I think the original author really meant this... */
|
|
...changed code here...</p>
|
|
|
|
<p>or:</p>
|
|
|
|
<p>/* FIXME: new code that *may* break something else... */ ...new
|
|
code here...</p>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 project).</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="SECT2">
|
|
<h2 class="SECT2"><a name="S46" id="S46">4.8. Addendum: Template for
|
|
files and function comment blocks:</a></h2>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example for file
|
|
comments:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
const char FILENAME_rcs[] = "$Id: coding.html,v 1.58 2011/12/26 17:06:24 fabiankeil Exp $";
|
|
/*********************************************************************
|
|
*
|
|
* File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
|
|
*
|
|
* Purpose : (Fill me in with a good description!)
|
|
*
|
|
* 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
|
|
* Public License as published by the Free Software
|
|
* Foundation; either version 2 of the License, or (at
|
|
* your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will
|
|
* be useful, but WITHOUT ANY WARRANTY; without even the
|
|
* implied warranty of MERCHANTABILITY or FITNESS FOR A
|
|
* PARTICULAR PURPOSE. See the GNU General Public
|
|
* License for more details.
|
|
*
|
|
* The GNU General Public License should be included with
|
|
* this file. If not, you can view it at
|
|
* 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
|
|
*
|
|
*********************************************************************/
|
|
|
|
|
|
#include "config.h"
|
|
|
|
...necessary include files for us to do our work...
|
|
|
|
const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</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 EMPHASIS c2">Note:</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 EMPHASIS c2">Example for file header
|
|
comments:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
#ifndef _FILENAME_H
|
|
#define _FILENAME_H
|
|
#define FILENAME_H_VERSION "$Id: coding.html,v 1.58 2011/12/26 17:06:24 fabiankeil Exp $"
|
|
/*********************************************************************
|
|
*
|
|
* File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
|
|
*
|
|
* Purpose : (Fill me in with a good description!)
|
|
*
|
|
* 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
|
|
* Public License as published by the Free Software
|
|
* Foundation; either version 2 of the License, or (at
|
|
* your option) any later version.
|
|
*
|
|
* This program is distributed in the hope that it will
|
|
* be useful, but WITHOUT ANY WARRANTY; without even the
|
|
* implied warranty of MERCHANTABILITY or FITNESS FOR A
|
|
* PARTICULAR PURPOSE. See the GNU General Public
|
|
* License for more details.
|
|
*
|
|
* The GNU General Public License should be included with
|
|
* this file. If not, you can view it at
|
|
* 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
|
|
*
|
|
*********************************************************************/
|
|
|
|
|
|
#include "project.h"
|
|
|
|
#ifdef __cplusplus
|
|
extern "C" {
|
|
#endif
|
|
|
|
... function headers here ...
|
|
|
|
|
|
/* Revision control strings from this header and associated .c file */
|
|
extern const char FILENAME_rcs[];
|
|
extern const char FILENAME_h_rcs[];
|
|
|
|
|
|
#ifdef __cplusplus
|
|
} /* extern "C" */
|
|
#endif
|
|
|
|
#endif /* ndef _FILENAME_H */
|
|
|
|
/*
|
|
Local Variables:
|
|
tab-width: 3
|
|
end:
|
|
*/
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Example for function
|
|
comments:</span></p>
|
|
|
|
<table class="c3" border="0" width="100%">
|
|
<tr>
|
|
<td>
|
|
<pre class="PROGRAMLISTING">
|
|
/*********************************************************************
|
|
*
|
|
* Function : FUNCTION_NAME
|
|
*
|
|
* Description : (Fill me in with a good description!)
|
|
*
|
|
* parameters :
|
|
* 1 : param1 = pointer to an important thing
|
|
* 2 : x = pointer to something else
|
|
*
|
|
* Returns : 0 => Ok, everything else is an error.
|
|
*
|
|
*********************************************************************/
|
|
int FUNCTION_NAME( void *param1, const char *x )
|
|
{
|
|
...
|
|
return( 0 );
|
|
|
|
}
|
|
</pre>
|
|
</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p><span class="emphasis EMPHASIS c2">Note:</span> If we all follow
|
|
this practice, we should be able to parse our code to create a
|
|
"self-documenting" web page.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="NAVFOOTER">
|
|
<hr class="c1" width="100%">
|
|
|
|
<table summary="Footer navigation table" width="100%" border="0"
|
|
cellpadding="0" cellspacing="0">
|
|
<tr>
|
|
<td width="33%" align="left" valign="top"><a href=
|
|
"documentation.html" accesskey="P">Prev</a></td>
|
|
|
|
<td width="34%" align="center" valign="top"><a href="index.html"
|
|
accesskey="H">Home</a></td>
|
|
|
|
<td width="33%" align="right" valign="top"><a href="testing.html"
|
|
accesskey="N">Next</a></td>
|
|
</tr>
|
|
|
|
<tr>
|
|
<td width="33%" align="left" valign="top">Documentation
|
|
Guidelines</td>
|
|
|
|
<td width="34%" align="center" valign="top"> </td>
|
|
|
|
<td width="33%" align="right" valign="top">Testing Guidelines</td>
|
|
</tr>
|
|
</table>
|
|
</div>
|
|
</body>
|
|
</html>
|