X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fwebserver%2Fdeveloper-manual%2Fcoding.html;h=3e2753ed5bea9b37934aaaeb26df0cc79c589820;hb=1f8e678f82936f21347922e1b2428ac00cd4d34e;hp=d30b7406d70407b160375a4d145263c7d1cd006c;hpb=321944b1997539a18dc73184c01a81f6b89acb65;p=privoxy.git diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index d30b7406..3e2753ed 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -1,11 +1,11 @@ +
Next | 6. Coding Guidelines4. Coding Guidelines
Exception:
If you are trying to add a small logic comment and do not @@ -233,12 +254,15 @@ CLASS="SECT3" CLASS="SECT3" >6.2.3. Keep Comments on their own line4.2.3. Keep Comments on their own line
Explanation:
It goes back to the question of readability. If the comment @@ -250,9 +274,12 @@ CLASS="EMPHASIS" at the end of closing braces, when used to comment parameters.
Example:
Explanation:
Logical steps should be commented to help others follow the @@ -332,12 +362,15 @@ CLASS="SECT3" CLASS="SECT3" >6.2.5. Comment All Functions Thoroughly4.2.5. Comment All Functions Thoroughly
Explanation:
A reader of the code should be able to look at the comments @@ -359,13 +392,16 @@ CLASS="SECT3" CLASS="SECT3" >6.2.6. Comment at the end of braces if the +>4.2.6. Comment at the end of braces if the content is more than one screen length
Explanation:
Each closing brace should be followed on the same line by a @@ -380,9 +416,12 @@ CLASS="EMPHASIS" >use following a closing brace: } /* -END- if() or while () or etc... */
Example:
if ( 1 == X ) +>if (1 == X) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... } /* -END- if x is 1 */ or: -if ( 1 == X ) +if (1 == X) { - DoSomethingVeryImportant(); + do_something_very_important(); ...some long list of commands... -} /* -END- if ( 1 == X ) */ |
Explanation:
Use all lowercase, and separate words via an underscore @@ -439,9 +481,12 @@ CLASS="EMPHASIS" template, class, true, false, ...). This is in case we ever decide to port Privoxy to C++.
Example:
Instead of:
Explanation:
Use all lowercase, and separate words via an underscore @@ -496,9 +545,12 @@ CLASS="EMPHASIS" template, class, true, false, ...). This is in case we ever decide to port Privoxy to C++.
Example:
int load_some_file( struct client_state *csp )int load_some_file(struct client_state *csp) |
Instead of:
int loadsomefile( struct client_state *csp ) -int loadSomeFile( struct client_state *csp )int loadsomefile(struct client_state *csp) +int loadSomeFile(struct client_state *csp) |
Explanation:
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.
Example:
(.h) extern int load_aclfile( struct client_state *csp ); -(.c) int load_aclfile( struct client_state *csp )(.h) extern int load_aclfile(struct client_state *csp); +(.c) int load_aclfile(struct client_state *csp) |
Instead of:
- Explanation: 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.) Example: Note: 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. Example: Explanation: Spell common words out entirely (do not remove vowels). Example: Instead of: Explanation: The brace needs to be on a line all by itself, not at the
@@ -744,9 +827,12 @@ CLASS="EMPHASIS"
easier to identify the opening and closing braces for a
block. Example: Instead of: if ( this == that ) { ... } or if ( this == that ) { ... } Note: 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. Status: developer-discretion. Example exception: Explanation: 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. Example: Instead of: if ( this == that ) DoSomething(); DoSomethingElse(); or if ( this == that ) DoSomething(); Note: 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
@@ -878,13 +988,16 @@ CLASS="SECT3"
CLASS="SECT3"
>6.4.3. Do not belabor/blow-up boolean
+>4.4.3. Do not belabor/blow-up boolean
expressions Example: Instead of: if ( condition ) { structure->flag = 1; } else {
+>if (condition) { structure->flag = 1; } else {
structure->flag = 0; } Note: 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
@@ -921,21 +1040,27 @@ CLASS="SECT3"
CLASS="SECT3"
>6.4.4. Use white space freely because it is
+>4.4.4. Use white space freely because it is
free Explanation: Make it readable. The notable exception to using white space
freely is listed in the next guideline. Example: Explanation: - structure pointer operator ( "->" ) - member operator (
@@ -980,9 +1104,12 @@ CLASS="EMPHASIS"
connection between the object and variable/function name is not
as clear. Example: Instead of: aStruct -> aMember; aStruct . aMember;
- FunctionName (); Example: 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
lines afterward. This makes the end of function standout to
the most casual viewer. Although function comments help
@@ -1061,9 +1200,12 @@ CLASS="EMPHASIS"
"do" loops, and long if {} statements too. After all whitespace
is free! Status: developer-discretion on the number of blank
lines. Enforced is the end of function comments. Explanation: If some use 8 character TABs and some use 3 character TABs,
@@ -1086,9 +1231,12 @@ CLASS="EMPHASIS"
only. If you like to use TABs, pass your code through a filter
such as "expand -t3" before checking in your code. Example: Explanation: Do not assume that the variables declared will not be used
@@ -1150,9 +1301,12 @@ CLASS="EMPHASIS"
the code. Remove the chance of accidentally using an unassigned
variable. Example: 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]. Status: developer-discretion if and only if the
variable is assigned a value "shortly after" declaration. Explanation: Value should be phrased as a question that would logically
be answered as a true or false statement Example: Explanation: The default return for a function is an int. To avoid
@@ -1255,21 +1424,27 @@ CLASS="SECT3"
CLASS="SECT3"
>6.6.3. Minimize function calls when iterating by
+>4.6.3. Minimize function calls when iterating by
using variables Explanation: It is easy to write the following code, and a clear argument
can be made that the code is easy to understand: Example: Note: 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 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,
assign the value to a variable, and evaluate using the
variable. Example: Exceptions: if the value of blockListLength() *may*
- change or could *potentially* change, then you must code the
+> 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. Explanation: 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 ); I could then not use it to compare argv's in main: int main(
- int argc, const char *argv[] ) { strcmp( argv[0], "privoxy"
- ); } Both these pointers are *const*! If the c runtime library
maintainers do it, we should too. Explanation: 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 ) would not work. So, to be consistent, we should declare all
- prototypes with "pass by value": int load_aclfile( struct
- client_state *csp ) Explanation: Your include statements should contain the file name without
@@ -1403,9 +1596,12 @@ CLASS="EMPHASIS"
partial path to distinguish their header files from system or
other header files. Example: Exception: Note: Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
"file.h" behavior. Explanation: Prevents compiler and linker errors resulting from
@@ -1471,9 +1674,12 @@ CLASS="EMPHASIS"
with your file name, with "." Changed to "_", and make it
uppercase. Example: Explanation: 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. Example: Explanation: Useful in headers that include pointers to other struct's.
Modifications to excess header files may cause needless
compiles. Example: Note: 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. Status: Use with discretion. Explanation Compiler warnings are meant to help you find bugs. You
@@ -1621,13 +1848,16 @@ CLASS="SECT3"
CLASS="SECT3"
>6.7.2. Provide a default case for all switch
+>4.7.2. Provide a default case for all switch
statements Explanation: What you think is guaranteed is never really guaranteed. The
@@ -1635,9 +1865,12 @@ CLASS="EMPHASIS"
someday will be passed. So, to protect yourself from the
unknown, always have a default step in a switch statement. Example: Note: 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. 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. Status: Programmer discretion is advised. Explanation: In general, you will want to have a 'break' statement within
@@ -1724,48 +1969,23 @@ CLASS="SECT3"
> Explanation: On 32-bit platforms, int usually has the range of long. On
- 16-bit platforms, int has the range of short. Status: 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? Explanation: 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. Explanation: It can be tempting to declare a series of variables all on
one line. Don't. Example: Instead of: long a, b, c; Explanation: - 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 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. Explanation: Create a local struct (on the stack) if the variable will
@@ -1853,9 +2094,12 @@ CLASS="EMPHASIS"
>Only "malloc" a struct (on the heap) if the variable's life
will extend beyond the context of one function call. Example: Explanation: If you have to "malloc" an instance, you are responsible for
@@ -1892,11 +2139,14 @@ CLASS="EMPHASIS"
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 accommodate this. Example: Exceptions: The developer cannot be expected to provide `free'ing
functions for C run-time library functions ... such as
`strdup'. Status: developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested). Explanation: 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. Note: 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
@@ -1961,36 +2223,42 @@ CLASS="SECT3"
CLASS="SECT3"
>6.7.10. "Uncertain" new code and/or changes to
- existing code, use FIXME4.7.9. "Uncertain" new code and/or changes to
+ existing code, use XXX Explanation: If you have enough confidence in new code or confidence in
your changes, but are not *quite* sure of the repercussions,
add this: /* FIXME: this code has a logic error on platform XYZ, *
+>/* XXX: this code has a logic error on platform XYZ, *
attempting to fix */ #ifdef PLATFORM ...changed code here...
#endif or: /* FIXME: I think the original author really meant this...
+>/* XXX: I think the original author really meant this...
*/ ...changed code here... or: /* FIXME: new code that *may* break something else... */
+>/* XXX: new code that *may* break something else... */
...new code here... Note: 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
@@ -2003,13 +2271,16 @@ CLASS="SECT2"
CLASS="SECT2"
>6.8. Addendum: Template for files and function
+>4.8. Addendum: Template for files and function
comment blocks: Example for file comments: Note: This declares the rcs variables that should be
- added to the "show-proxy-args" page. If this is a brand new
+ added to the "show-version" 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. Note: 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. Example for file header comments: Example for function comments: Note: If we all follow this practice, we should be
able to parse our code to create a "self-documenting" web
page.(.h) extern int load_aclfile( struct client_state * ); or
-(.h) extern int load_aclfile();
-(.c) int load_aclfile( struct client_state *csp )
(.h) extern int load_aclfile(struct client_state *); or
+(.h) extern int load_aclfile();
+(.c) int load_aclfile(struct client_state *csp)(enumeration) : enum Boolean { FALSE, TRUE };
+>(enumeration) : enum Boolean {FALSE, TRUE};
(#define) : #define DEFAULT_SIZE 100;
6.3.5. Constants4.3.5. Constants
#define USE_IMG_LST 1 or
+>#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
if ( this == that )
+>if (this == that)
{
...
}
6.4.2. ALL control statements should have a
+>4.4.2. ALL control statements should have a
blockwhile ( more lines are read )
+>while (more lines are read)
{
/* Please document what is/is not a comment line here */
- if ( it's a comment ) continue;
+ if (it's a comment) continue;
- do_something( line );
+ do_something(line);
}
if ( this == that )
+>if (this == that)
{
- DoSomething();
- DoSomethingElse();
+ do_something();
+ do_something_else();
}
structure->flag = ( condition );
structure->flag = (condition);
6.4.5. Don't use white space around structure
+>4.4.5. Don't use white space around structure
operatorsint firstValue = 0;
-int someValue = 0;
-int anotherValue = 0;
-int thisVariable = 0;
-
-if ( thisVariable == thatVariable )
-
-firstValue = oldValue + ( ( someValue - anotherValue ) - whatever )
int first_value = 0;
+int some_value = 0;
+int another_value = 0;
+int this_variable = 0;aStruct->aMember;
-aStruct.aMember;
-FunctionName();
a_struct->a_member;
+a_struct.a_member;
+function_name();int function1( ... )
{
...code...
- return( retCode );
+ return(ret_code);
-} /* -END- function1 */
+} /* -END- function1 */
int function2( ... )
{
-} /* -END- function2 */
6.5. Initializing4.5. Initializing
short anShort = 0;
-float aFloat = 0;
+>short a_short = 0;
+float a_float = 0;
struct *ptr = NULL;
6.6.2. Always specify a return type for a
+>4.6.2. Always specify a return type for a
function.ShouldWeBlockThis();
-ContainsAnImage();
-IsWebPageBlank();
should_we_block_this();
+contains_an_image();
+is_web_page_blank();for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ )
+>for (size_t cnt = 0; cnt < block_list_length(); cnt++)
{
....
}
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++)
{
....
}
/* This is not a local include, but requires a path element. */
+>/* This is not a local include, but requires a path element. */
#include <sys/fileName.h>
6.6.8. Use `extern "C"` when appropriate4.6.8. Use `extern "C"` when appropriate
6.6.9. Where Possible, Use Forward Struct
+>4.6.9. Where Possible, Use Forward Struct
Declaration Instead of Includes
switch( hash_string( cmd ) )
+>switch (hash_string(cmd))
{
- case hash_actions_file :
+ case hash_actions_file:
... code ...
break;
- case hash_confdir :
+ case hash_confdir:
... code ...
break;
- default :
+ default:
log_error( ... );
... anomaly code goes here ...
continue; / break; / exit( 1 ); / etc ...
-} /* end switch( hash_string( cmd ) ) */
6.7.4. Use 'long' or 'short' Instead of
- 'int'
6.7.5. Don't mix size_t and other types4.7.4. Don't mix size_t and other types
6.7.8. The Programmer Who Uses 'malloc' is
+>4.7.7. The Programmer Who Uses 'malloc' is
Responsible for Ensuring 'free'
int load_re_filterfile( struct client_state *csp ) { ... }
-static void unload_re_filterfile( void *f ) { ... }
int load_re_filterfile(struct client_state *csp) { ... }
+static void unload_re_filterfile(void *f) { ... }const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.39 2002/05/02 15:08:25 oes Exp $";
-/*********************************************************************
+>/*********************************************************************
*
- * File : $Source$
+ * 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
+ * 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
@@ -2047,12 +2313,10 @@ CLASS="PROGRAMLISTING"
*
* 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$
+ * 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
*
*********************************************************************/
@@ -2066,26 +2330,35 @@ const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.39 2002/05/02 15:08:25 oes Exp $"
/*********************************************************************
*
- * File : $Source$
+ * 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
+ * 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
@@ -2125,12 +2393,10 @@ CLASS="PROGRAMLISTING"
*
* 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$
+ * 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
*
*********************************************************************/
@@ -2164,9 +2430,12 @@ extern const char FILENAME_h_rcs[];
>
Prev
Home Next