-<!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=ISO-8859-1"></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"
->4. Coding Guidelines</A
-></H1
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="S1"
->4.1. Introduction</A
-></H2
-><P
->This set of standards is designed to make our lives easier. It is
- developed with the simple goal of helping us keep the "new and improved
- <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"
->4.2. Using Comments</A
-></H2
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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 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"
-><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 )
+<!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, 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=ISO-8859-1">
+<style type="text/css">
+ body {
+ background-color: #EEEEEE;
+ color: #000000;
+ }
+ :link { color: #0000FF }
+ :visited { color: #840084 }
+ :active { color: #0000FF }
+ 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 width="100%" class="c1">
+ </div>
+ <div class="SECT1">
+ <h1 class="SECT1">
+ <a name="CODING">4. Coding Guidelines</a>
+ </h1>
+ <div class="SECT2">
+ <h2 class="SECT2">
+ <a name="S1">4.1. Introduction</a>
+ </h2>
+ <p>
+ This set of standards is designed to make our lives easier. It is
+ developed with the simple goal of helping us keep the "new and
+ improved <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">4.2. Using Comments</a>
+ </h2>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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 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"><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 )
+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"
->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"
->/*********************************************************************
+is actually being done.
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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 )
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"
->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"
->/*********************************************************************
+}
+</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">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.
*********************************************************************/
{
...code here...
-} /* -END- do_something_very_important */</PRE
-></TD
-></TR
-></TABLE
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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"
->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"
->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 )
+} /* -END- do_something_very_important */
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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">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">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...
{
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"
->4.3. Naming Conventions</A
-></H2
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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
-><P
-><TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->int msiis5hack = 0; int msIis5Hack = 0;</PRE
-></TD
-></TR
-></TABLE
-></P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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
-><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
-></P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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
->
-<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
-></P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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
+} /* -END- if ( 1 == X ) */
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ <div class="SECT2">
+ <h2 class="SECT2">
+ <a name="S9">4.3. Naming Conventions</a>
+ </h2>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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">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">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">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"
->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
-><P
-><TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->#define USE_IMG_LST 1 or
+#endif /* def FEATURE_FORCE */
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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 use_image_list 1 or
-#define UseImageList 1</PRE
-></TD
-></TR
-></TABLE
-></P
-></DIV
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="S15"
->4.4. Using Space</A
-></H2
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S16"
->4.4.1. Put braces on a line by themselves.</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 )
+#define UseImageList 1
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ <div class="SECT2">
+ <h2 class="SECT2">
+ <a name="S15">4.4. Using Space</a>
+ </h2>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="S16">4.4.1. Put braces on a line by themselves.</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 )
+}
+</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"
->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 )
+}
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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"
->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"
->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;
+}
+</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">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">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;
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"
->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;
+first_value = old_value + ( ( some_value - another_value ) - whatever )
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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"
->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( ... )
+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">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 );
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"
->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] =
+} /* -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">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, ...
};
return( NEVER_GETS_HERE );
-}</PRE
-></TD
-></TR
-></TABLE
-></DIV
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="S23"
->4.5. Initializing</A
-></H2
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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;
+}
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ </div>
+ <div class="SECT2">
+ <h2 class="SECT2">
+ <a name="S23">4.5. Initializing</a>
+ </h2>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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"
->4.6. Functions</A
-></H2
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S26"
->4.6.1. Name functions that return a boolean as a
- question.</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();
+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">4.6. Functions</a>
+ </h2>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="S26">4.6.1. Name functions that return a boolean as a
+ question.</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"
->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"
->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++ )
+is_web_page_blank();
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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">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();
+}
+</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++ )
+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"
->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"
->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"
->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
-><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
-><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"
->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
+}
+</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">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">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">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">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"
->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
+#endif /* ndef PROJECT_H_INCLUDED */
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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 */
#ifdef __cplusplus
}
-#endif /* def __cplusplus */</PRE
-></TD
-></TR
-></TABLE
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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"
->/*********************************************************************
+#endif /* def __cplusplus */
+</pre>
+ </td>
+ </tr>
+ </table>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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"
->4.7. General Coding Practices</A
-></H2
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="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"
->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 ) )
+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">4.7. General Coding Practices</a>
+ </h2>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="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">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 ...
... 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"
->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="S39"
->4.7.4. Use 'long' or 'short' Instead of
- 'int'</A
-></H3
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></SPAN
-></P
-><P
->On 32-bit platforms, int usually has the range of long. On
- 16-bit platforms, int has the range of short.</P
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Status:</I
-></SPAN
-> open-to-debate. In the case of most FSF
- projects (including X/GNU-Emacs), there are typedefs to int4,
- int8, int16, (or equivalence ... I forget the exact typedefs
- 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"
->4.7.5. Don't mix size_t and other types</A
-></H3
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></SPAN
-></P
-><P
->The type of size_t varies across platforms. Do not make
- assumptions about whether it is signed or unsigned, or about
- how long it is. Do not compare a size_t against another
- variable of a different type (or even against a constant)
- without casting one of the values.</P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S41"
->4.7.6. Declare each variable and struct on its
- own line.</A
-></H3
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></SPAN
-></P
-><P
->It can be tempting to declare a series of variables all on
- one line. Don't.</P
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Example:</I
-></SPAN
-></P
-><TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->long a = 0;
+} /* 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">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="S39">4.7.4. Use 'long' or 'short' Instead of 'int'</a>
+ </h3>
+ <p>
+ <span class="emphasis"><i class=
+ "EMPHASIS">Explanation:</i></span>
+ </p>
+ <p>
+ On 32-bit platforms, int usually has the range of long. On 16-bit
+ platforms, int has the range of short.
+ </p>
+ <p>
+ <span class="emphasis"><i class="EMPHASIS">Status:</i></span>
+ open-to-debate. In the case of most FSF projects (including
+ X/GNU-Emacs), there are typedefs to int4, int8, int16, (or
+ equivalence ... I forget the exact typedefs 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">4.7.5. Don't mix size_t and other types</a>
+ </h3>
+ <p>
+ <span class="emphasis"><i class=
+ "EMPHASIS">Explanation:</i></span>
+ </p>
+ <p>
+ The type of size_t varies across platforms. Do not make
+ assumptions about whether it is signed or unsigned, or about how
+ long it is. Do not compare a size_t against another variable of a
+ different type (or even against a constant) without casting one
+ of the values.
+ </p>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="S41">4.7.6. Declare each variable and struct on its own
+ line.</a>
+ </h3>
+ <p>
+ <span class="emphasis"><i class=
+ "EMPHASIS">Explanation:</i></span>
+ </p>
+ <p>
+ It can be tempting to declare a series of variables all on one
+ line. Don't.
+ </p>
+ <p>
+ <span class="emphasis"><i class="EMPHASIS">Example:</i></span>
+ </p>
+ <table border="0" 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"
->4.7.7. Use malloc/zalloc sparingly</A
-></H3
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></SPAN
-></P
-><P
->Create a local struct (on the stack) if the variable will
- 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"
->4.7.8. The Programmer Who Uses 'malloc' is
- Responsible for Ensuring 'free'</A
-></H3
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></SPAN
-></P
-><P
->If you have to "malloc" an instance, you are responsible for
- 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"
->4.7.9. Add loaders to the `file_list' structure
- and in order</A
-></H3
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></SPAN
-></P
-><P
->I have ordered all of the "blocker" file code to be in alpha
- order. It is easier to add/read new blockers when you expect a
- certain order.</P
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Note:</I
-></SPAN
-> It may appear that the alpha order is broken in
- places by POPUP tests coming before PCRS tests. But since
- POPUPs can also be referred to as KILLPOPUPs, it is clear that
- it should come first.</P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S45"
->4.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME or XXX</A
-></H3
-><P
-><SPAN
-CLASS="emphasis"
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></SPAN
-></P
-><P
->If you have enough confidence in new code or confidence in
- 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"
-><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"
->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[] = "$Id$";
+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">4.7.7. Use malloc/zalloc sparingly</a>
+ </h3>
+ <p>
+ <span class="emphasis"><i class=
+ "EMPHASIS">Explanation:</i></span>
+ </p>
+ <p>
+ Create a local struct (on the stack) if the variable will 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">4.7.8. The Programmer Who Uses 'malloc' is
+ Responsible for Ensuring 'free'</a>
+ </h3>
+ <p>
+ <span class="emphasis"><i class=
+ "EMPHASIS">Explanation:</i></span>
+ </p>
+ <p>
+ If you have to "malloc" an instance, you are responsible for
+ 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">4.7.9. Add loaders to the `file_list' structure and
+ in order</a>
+ </h3>
+ <p>
+ <span class="emphasis"><i class=
+ "EMPHASIS">Explanation:</i></span>
+ </p>
+ <p>
+ I have ordered all of the "blocker" file code to be in alpha
+ order. It is easier to add/read new blockers when you expect a
+ certain order.
+ </p>
+ <p>
+ <span class="emphasis"><i class="EMPHASIS">Note:</i></span> It
+ may appear that the alpha order is broken in places by POPUP
+ tests coming before PCRS tests. But since POPUPs can also be
+ referred to as KILLPOPUPs, it is clear that it should come first.
+ </p>
+ </div>
+ <div class="SECT3">
+ <h3 class="SECT3">
+ <a name="S45">4.7.10. "Uncertain" new code and/or changes to
+ existing code, use FIXME or XXX</a>
+ </h3>
+ <p>
+ <span class="emphasis"><i class=
+ "EMPHASIS">Explanation:</i></span>
+ </p>
+ <p>
+ If you have enough confidence in new code or confidence in 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"><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">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[] = "$Id: coding.html,v 1.54 2010/11/13 12:50:18 fabiankeil Exp $";
/*********************************************************************
*
- * File : $Source$
+ * File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
*
* Purpose : (Fill me in with a good description!)
*
* 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.,
+ * or write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
* USA
*
...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
+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 "$Id$"
+#define FILENAME_H_VERSION "$Id: coding.html,v 1.54 2010/11/13 12:50:18 fabiankeil Exp $"
/*********************************************************************
*
- * File : $Source$
+ * File : $Source: /cvsroot/ijbswa/current/doc/webserver/developer-manual/coding.html,v $
*
* Purpose : (Fill me in with a good description!)
*
* 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.,
+ * or write to the Free Software Foundation, Inc.,
* 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 ,
* USA
*
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"
->/*********************************************************************
+*/
+</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
*
* 1 : param1 = pointer to an important thing
* 2 : x = pointer to something else
*
- * Returns : 0 => Ok, everything else is an error.
+ * 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
->
\ No newline at end of file
+}
+</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 width="100%" class="c1">
+ <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>
+
projects / privoxy.git / blobdiff