-} /* end switch( hash_string( cmd ) ) */</PRE
-></TD
-></TR
-></TABLE
-><P
-><I
-CLASS="EMPHASIS"
->Note:</I
-> 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
-><I
-CLASS="EMPHASIS"
->Another Note:</I
-> This is not so much a readability issue
- as a robust programming issue. The "anomly code goes here" may
- be no more than a print to the STDERR stream (as in
- load_config). Or it may really be an ABEND condition.</P
-><P
-><I
-CLASS="EMPHASIS"
->Status:</I
-> Programmer discretion is advised.</P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S38"
->5.7.3. Try to avoid falling through cases in a
- switch statement.</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></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"
->5.7.4. Use 'long' or 'short' Instead of
- 'int'</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></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
-><I
-CLASS="EMPHASIS"
->Status:</I
-> 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"
->5.7.5. Don't mix size_t and other types</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></P
-><P
->The type of size_t varies across platforms. Do not make
- assumptions about whether it is signed or unsigned, or about
- how long it is. Do not compare a size_t against another
- variable of a different type (or even against a constant)
- without casting one of the values. Try to avoid using size_t if
- you can.</P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S41"
->5.7.6. Declare each variable and struct on its
- own line.</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></P
-><P
->It can be tempting to declare a series of variables all on
- one line. Don't.</P
-><P
-><I
-CLASS="EMPHASIS"
->Example:</I
-></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
-><I
-CLASS="EMPHASIS"
->Instead of:</I
-></P
-><P
->long a, b, c;</P
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-> - 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
-><I
-CLASS="EMPHASIS"
->Exceptions:</I
-> when you want to declare a bunch of loop
- variables or other trivial variables; feel free to declare them
- on 1 line. You should, although, provide a good comment on
- their functions.</P
-><P
-><I
-CLASS="EMPHASIS"
->Status:</I
-> developer-discrection.</P
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S42"
->5.7.7. Use malloc/zalloc sparingly</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></P
-><P
->Create a local stuct (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
-><I
-CLASS="EMPHASIS"
->Example:</I
-></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 definately be allocated via `malloc'.</PRE
-></TD
-></TR
-></TABLE
-></DIV
-><DIV
-CLASS="SECT3"
-><H3
-CLASS="SECT3"
-><A
-NAME="S43"
->5.7.8. The Programmer Who Uses 'malloc' is
- Responsible for Ensuring 'free'</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></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/destuctor type function to accomodate this.</P
-><P
-><I
-CLASS="EMPHASIS"
->Example:</I
-></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
-><I
-CLASS="EMPHASIS"
->Exceptions:</I
-></P
-><P
->The developer cannot be expected to provide `free'ing
- functions for C run-time library functions ... such as
- `strdup'.</P
-><P
-><I
-CLASS="EMPHASIS"
->Status:</I
-> developer-discrection. 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"
->5.7.9. Add loaders to the `file_list' structure
- and in order</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></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
-><I
-CLASS="EMPHASIS"
->Note:</I
-> 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"
->5.7.10. "Uncertain" new code and/or changes to
- exitinst code, use FIXME</A
-></H3
-><P
-><I
-CLASS="EMPHASIS"
->Explanation:</I
-></P
-><P
->If you have enough confidence in new code or confidence in
- your changes, but are not *quite* sure of the reprocussions,
- add this:</P
-><P
->/* FIXME: this code has a logic error on platform XYZ, *
- attempthing 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
-><I
-CLASS="EMPHASIS"
->Note:</I
-> 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 conversly exclude from the
- project).</P
-></DIV
-></DIV
-><DIV
-CLASS="SECT2"
-><H2
-CLASS="SECT2"
-><A
-NAME="S46"
->5.8. Addendum: Template for files and function
- comment blocks:</A
-></H2
-><P
-><I
-CLASS="EMPHASIS"
->Example for file comments:</I
-></P
-><TABLE
-BORDER="0"
-BGCOLOR="#E0E0E0"
-WIDTH="100%"
-><TR
-><TD
-><PRE
-CLASS="PROGRAMLISTING"
->const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $";
-/*********************************************************************
- *
- * File : $Source$
- *
- * Purpose : (Fill me in with a good description!)
- *
- * Copyright : Written by and Copyright (C) 2001 the SourceForge
- * Privoxy team. http://www.privoxy.org/
- *
- * Based on the Internet Junkbuster originally written
- * by and Copyright (C) 1997 Anonymous Coders and
- * Junkbusters Corporation. http://www.junkbusters.com
- *
- * 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/copyleft/gpl.html
- * or write to the Free Software Foundation, Inc., 59
- * Temple Place - Suite 330, Boston, MA 02111-1307, USA.
- *
- * Revisions :
- * $Log$
- *
- *********************************************************************/
+ } /* 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"> /*********************************************************************
+ *
+ * File : $Source
+ *
+ * Purpose : (Fill me in with a good description!)
+ *
+ * Copyright : Written by and Copyright (C) 2001-2009
+ * the Privoxy team. https://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
+ *
+ *********************************************************************/