X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;f=doc%2Fsource%2Fdeveloper-manual.sgml;h=be9ff4ea73ef3fb94d47d58b995f7a96d53f1a6e;hb=573c8a27abc6c8df5bfd7ea90b5e4dcbac33151f;hp=362b5f5bbbc26e6173bc67aba9a7fdc9410905e7;hpb=be490aaf495531c679f5eec40c2f548ff3d56d2c;p=privoxy.git
diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml
index 362b5f5b..be9ff4ea 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.10 2006/09/22 01:27:55 hal9 Exp $
+ $Id: developer-manual.sgml,v 2.12 2006/11/14 01:57:46 hal9 Exp $
- Copyright (C) 2001-2006 Privoxy Developers http://privoxy.org
+ Copyright (C) 2001-2007 Privoxy Developers http://www.privoxy.org/
See LICENSE.
========================================================================
@@ -44,13 +44,13 @@
- Copyright &my-copy; 2001-2006 by
- Privoxy Developers
+ Copyright &my-copy; 2001-2007 by
+ Privoxy Developers
- $Id: developer-manual.sgml,v 2.10 2006/09/22 01:27:55 hal9 Exp $
+ $Id: developer-manual.sgml,v 2.12 2006/11/14 01:57:46 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.
@@ -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.10 2006/09/22 01:27:55 hal9 Exp $";
+const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 2.12 2006/11/14 01:57:46 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001-2006 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
@@ -1893,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.10 2006/09/22 01:27:55 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 2.12 2006/11/14 01:57:46 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
*
* Purpose : (Fill me in with a good description!)
*
- * Copyright : Written by and Copyright (C) 2001-2006 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
@@ -3025,6 +3026,13 @@ at sourceforge. Three simple steps:
Temple Place - Suite 330, Boston, MA 02111-1307, USA.
$Log: developer-manual.sgml,v $
+ 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.