X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=585cddb1765b46057eccab0f0b5b266b522b734f;hb=fe2dba94b00d45349597603a45cca6456c03fe54;hp=708dad10b8f674fc52e560018a8af16a4ed8da74;hpb=0cb45319db94896cd3bc09b3e19789ebb1a30192;p=privoxy.git diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index 708dad10..585cddb1 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -8,10 +8,10 @@ - - - - + + + + @@ -23,9 +23,9 @@ This file belongs into ijbswa.sourceforge.net:/home/groups/i/ij/ijbswa/htdocs/ - $Id: developer-manual.sgml,v 2.8 2006/08/22 23:35:01 hal9 Exp $ + $Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $ - Copyright (C) 2001-2006 Privoxy Developers + Copyright (C) 2001-2008 Privoxy Developers http://www.privoxy.org/ See LICENSE. ======================================================================== @@ -44,13 +44,13 @@ - Copyright &my-copy; 2001-2006 by - Privoxy Developers + Copyright &my-copy; 2001-2008 by + Privoxy Developers - $Id: developer-manual.sgml,v 2.8 2006/08/22 23:35:01 hal9 Exp $ + $Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $ @@ -119,16 +120,17 @@ Hal. --> Privoxy, as an heir to - Junkbuster, is an Open Source project - and licensed under the GPL. As such, Privoxy - development is potentially open to anyone who has the time, knowledge, - and desire to contribute in any capacity. Our goals are simply to - continue the mission, to improve Privoxy, and + Junkbuster, is a Free Software project + and the code is licensed under the GPL. As such, + Privoxy development is potentially open + to anyone who has the time, knowledge, and desire to contribute + in any capacity. Our goals are simply to continue the mission, + to improve Privoxy, and to make it available to as wide an audience as possible. One does not have to be a programmer to contribute. Packaging, testing, - and porting, are all important jobs as well. + documenting and porting, are all important jobs as well. @@ -503,7 +505,7 @@ Hal. You might also find Writing Documentation + url="http://opensource.bureau-cornavin.com/crash-course/index.html">Writing Documentation Using DocBook - A Crash Course useful. @@ -731,8 +733,8 @@ Hal. Explanation: Comment as much as possible without commenting the obvious. - For example do not comment "aVariable is equal to bVariable". - Instead explain why aVariable should be equal to the bVariable. + 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 @@ -746,13 +748,13 @@ Hal. Example: /* if page size greater than 1k ... */ -if ( PageLength() > 1024 ) +if ( page_length() > 1024 ) { ... "block" the page up ... } /* if page size is small, send it in blocks */ -if ( PageLength() > 1024 ) +if ( page_length() > 1024 ) { ... "block" the page up ... } @@ -780,22 +782,22 @@ is actually being done. /********************************************************************* * This will stand out clearly in your code! *********************************************************************/ -if ( thisVariable == thatVariable ) +if ( this_variable == that_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } /* unfortunately, this may not */ -if ( thisVariable == thatVariable ) +if ( this_variable == that_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -if ( thisVariable == thatVariable ) /* this may not either */ +if ( this_variable == that_variable ) /* this may not either */ { - DoSomethingVeryImportant(); + do_something_very_important(); } Exception: @@ -827,14 +829,14 @@ if ( thisVariable == thatVariable ) /* this may not either */ * This will stand out clearly in your code, * But the second example won't. *********************************************************************/ -if ( thisVariable == thatVariable ) +if ( this_variable == this_variable ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -if ( thisVariable == thatVariable ) /*can you see me?*/ +if ( this_variable == this_variable ) /*can you see me?*/ { - DoSomethingVeryImportant(); /*not easily*/ + do_something_very_important(); /*not easily*/ } @@ -846,17 +848,17 @@ int urls_rejected = 0; /* # of urls rejected */ if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); } -short DoSomethingVeryImportant( +short do_something_very_important( short firstparam, /* represents something */ short nextparam /* represents something else */ ) { ...code here... -} /* -END- DoSomethingVeryImportant */ +} /* -END- do_something_very_important */ @@ -923,7 +925,7 @@ short DoSomethingVeryImportant( if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if x is 1 */ @@ -931,7 +933,7 @@ or: if ( 1 == X ) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if ( 1 == X ) */ @@ -1148,17 +1150,17 @@ while ( more lines are read ) if ( this == that ) { - DoSomething(); - DoSomethingElse(); + do_something(); + do_something_else(); } Instead of: - if ( this == that ) DoSomething(); DoSomethingElse(); + if ( this == that ) do_something(); do_something_else(); or - if ( this == that ) DoSomething(); + if ( this == that ) do_something(); Note: The first example in "Instead of" will execute in a manner other than that which the developer desired (per @@ -1201,14 +1203,14 @@ structure->flag = ( condition ); Example: -int firstValue = 0; -int someValue = 0; -int anotherValue = 0; -int thisVariable = 0; +int first_value = 0; +int some_value = 0; +int another_value = 0; +int this_variable = 0; -if ( thisVariable == thatVariable ) +if ( this_variable == this_variable ) -firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) +first_value = old_value + ( ( some_value - another_value ) - whatever ) @@ -1228,12 +1230,12 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) Example: -aStruct->aMember; -aStruct.aMember; -FunctionName(); +a_struct->a_member; +a_struct.a_member; +function_name(); - Instead of: aStruct -> aMember; aStruct . aMember; - FunctionName (); + Instead of: a_struct -> a_member; a_struct . a_member; + function_name (); @@ -1247,7 +1249,7 @@ FunctionName(); int function1( ... ) { ...code... - return( retCode ); + return( ret_code ); } /* -END- function1 */ @@ -1259,7 +1261,7 @@ int function2( ... ) Instead of: - int function1( ... ) { ...code... return( retCode ); } int + int function1( ... ) { ...code... return( ret_code ); } int function2( ... ) { } Note: Use 1 blank line before the closing brace and 2 @@ -1329,14 +1331,14 @@ int function1( ... ) Example: -short anShort = 0; -float aFloat = 0; +short a_short = 0; +float a_float = 0; struct *ptr = NULL; Note: It is much easier to debug a SIGSEGV if the message says you are trying to access memory address 00000000 - and not 129FA012; or arrayPtr[20] causes a SIGSEV vs. - arrayPtr[0]. + and not 129FA012; or array_ptr[20] causes a SIGSEV vs. + array_ptr[0]. Status: developer-discretion if and only if the variable is assigned a value "shortly after" declaration. @@ -1359,9 +1361,9 @@ struct *ptr = NULL; Example: -ShouldWeBlockThis(); -ContainsAnImage(); -IsWebPageBlank(); +should_we_block_this(); +contains_an_image(); +is_web_page_blank(); @@ -1390,7 +1392,7 @@ IsWebPageBlank(); Example: -for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) +for ( size_t cnt = 0; cnt < block_list_length(); cnt++ ) { .... } @@ -1399,10 +1401,10 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) 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 blockListLength() call, it might even be creating and + 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 blockListLength() is a function + Remember too - even a call to block_list_length() is a function call, with the same overhead. Instead of using a function call during the iterations, @@ -1411,15 +1413,15 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) Example: -size_t len = blockListLength(); +size_t len = block_list_length(); -for ( size_t cnt = 0; cnt < len; cnt ++ ) +for ( size_t cnt = 0; cnt < len; cnt++ ) { .... } - Exceptions: if the value of blockListLength() *may* - change or could *potentially* change, then you must code the + Exceptions: 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. @@ -1625,7 +1627,7 @@ switch( hash_string( cmd ) ) Another Note: This is not so much a readability issue as a robust programming issue. The "anomaly code goes here" may be no more than a print to the STDERR stream (as in - load_config). Or it may really be an ABEND condition. + load_config). Or it may really be an abort condition. Status: Programmer discretion is advised. @@ -1684,8 +1686,7 @@ switch( hash_string( cmd ) ) 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. + without casting one of the values. @@ -1717,7 +1718,7 @@ long c = 0; Exceptions: 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 + on one line. You should, although, provide a good comment on their functions. Status: developer-discretion. @@ -1795,7 +1796,7 @@ static void unload_re_filterfile( void *f ) { ... } "Uncertain" new code and/or changes to - existing code, use FIXME + existing code, use FIXME or XXX Explanation: @@ -1832,14 +1833,14 @@ static void unload_re_filterfile( void *f ) { ... } Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.8 2006/08/22 23:35:01 hal9 Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $"; /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge + * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1862,7 +1863,8 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.8 2006/08/22 23:35:0 * this file. If not, you can view it at * http://www.gnu.org/copyleft/gpl.html * or write to the Free Software Foundation, Inc., - * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * * Revisions : * $Log$ @@ -1892,14 +1894,14 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.8 2006/08/22 23:35:01 hal9 Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.15 2008/01/19 15:03:05 hal9 Exp $" /********************************************************************* * * File : $Source$ * * Purpose : (Fill me in with a good description!) * - * Copyright : Written by and Copyright (C) 2001 the SourceForge + * Copyright : Written by and Copyright (C) 2001-2007 the SourceForge * Privoxy team. http://www.privoxy.org/ * * Based on the Internet Junkbuster originally written @@ -1921,8 +1923,9 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION; * 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. + * or write to the Free Software Foundation, Inc., + * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 , + * USA * * Revisions : * $Log$ @@ -3023,6 +3026,35 @@ at sourceforge. Three simple steps: Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ + Revision 2.15 2008/01/19 15:03:05 hal9 + Doc sources tagged for 3.0.8 release. + + Revision 2.14 2008/01/17 01:49:51 hal9 + Change copyright notice for docs s/2007/2008/. All these will be rebuilt soon + enough. + + Revision 2.13 2007/10/30 17:59:31 fabiankeil + - Bump p-version, p-status and copyright date. + - Mention that the manual is out of date. + - Don't use examples with HardToReadCamelCase after + explaining that we actually don't like that. + - Minor cosmetics. + + Revision 2.12 2006/11/14 01:57:46 hal9 + Dump all docs prior to 3.0.6 release. Various minor changes to faq and user + manual. + + Revision 2.11 2006/09/26 02:36:29 hal9 + Fix broken link per bug tracker. + + Revision 2.10 2006/09/22 01:27:55 hal9 + Final commit of probably various minor changes here and there. Unless + something changes this should be ready for pending release. + + Revision 2.9 2006/09/14 02:30:07 hal9 + Fix ijbswa cvs links. Update notes on release process, and which config files + should be overwritten and which not. + Revision 2.8 2006/08/22 23:35:01 hal9 Fix email address, cvs URI, address branching changes and various other small updates.