--- /dev/null
+<!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.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">
+</head>
+
+<body class="SECT1" bgcolor="#EEEEEE" text="#000000" link="#0000FF" vlink=
+"#840084" alink="#0000FF">
+ <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 align="left" 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"><i class=
+ "EMPHASIS">Explanation:</i></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 fellow Privoxy
+ developers 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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Exception:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+int ms_iis5_hack = 0;
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+int load_some_file(struct client_state *csp)
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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" bgcolor="#E0E0E0" 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"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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" bgcolor="#E0E0E0" 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"><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" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+#define USE_IMAGE_LIST 1
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+if (this == that)
+{
+ ...
+}
+</pre>
+ </td>
+ </tr>
+ </table>
+
+ <p><span class="emphasis"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <p>if (this == that) { ... }</p>
+
+ <p>or</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" bgcolor="#E0E0E0" 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"><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" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+if (this == that)
+{
+ 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) do_something(); do_something_else();</p>
+
+ <p>or</p>
+
+ <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 "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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+structure->flag = (condition);
+</pre>
+ </td>
+ </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 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"><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" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+int first_value = 0;
+int some_value = 0;
+int another_value = 0;
+int this_variable = 0;
+</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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class="EMPHASIS">Instead of:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class="EMPHASIS">Instead
+ of:</i></span></p>
+
+ <p>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 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"><i class="EMPHASIS">Status:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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 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>
+ </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"><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" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Explanation:</i></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"><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" bgcolor="#E0E0E0" 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"><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 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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class="EMPHASIS">Exceptions:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><i class=
+ "EMPHASIS">Exception:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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>
+ </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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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" bgcolor="#E0E0E0" 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"><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" bgcolor="#E0E0E0" 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"><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>
+
+ <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"><i class=
+ "EMPHASIS">Explanation</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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 abort condition.</p>
+
+ <p><span class="emphasis"><i class="EMPHASIS">Status:</i></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"><i class=
+ "EMPHASIS">Explanation:</i></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="S40" id="S40">4.7.4. 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.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S41" id="S41">4.7.5. 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" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+long a = 0;
+long b = 0;
+long c = 0;
+</pre>
+ </td>
+ </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 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">
+ <h3 class="SECT3"><a name="S42" id="S42">4.7.6. 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 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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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.7. 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
+ 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"><i class="EMPHASIS">Example:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S44" id="S44">4.7.8. 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 it should come first.</p>
+ </div>
+
+ <div class="SECT3">
+ <h3 class="SECT3"><a name="S45" id="S45">4.7.9. "Uncertain" new code
+ and/or changes to existing code, use 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 your
+ changes, but are not *quite* sure of the repercussions, add this:</p>
+
+ <p>/* XXX: this code has a logic error on platform XYZ, * attempting
+ to fix */ #ifdef PLATFORM ...changed code here... #endif</p>
+
+ <p>or:</p>
+
+ <p>/* XXX: I think the original author really meant this... */
+ ...changed code here...</p>
+
+ <p>or:</p>
+
+ <p>/* XXX: 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 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"><i class="EMPHASIS">Example for file
+ comments:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$";
+/*********************************************************************
+ *
+ * File : $S<!-- Break CVS Substitution -->ource$
+ *
+ * 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"><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" bgcolor="#E0E0E0" width="100%">
+ <tr>
+ <td>
+ <pre class="PROGRAMLISTING">
+#ifndef _FILENAME_H
+#define _FILENAME_H
+#define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$"
+/*********************************************************************
+ *
+ * File : $S<!-- Break CVS Substitution -->ource$
+ *
+ * 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"><i class="EMPHASIS">Example for function
+ comments:</i></span></p>
+
+ <table border="0" bgcolor="#E0E0E0" 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"><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>
+ </div>
+ </div>
+
+ <div class="NAVFOOTER">
+ <hr align="left" 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>