X-Git-Url: http://www.privoxy.org/gitweb/?p=privoxy.git;a=blobdiff_plain;f=doc%2Fwebserver%2Fdeveloper-manual%2Fcoding.html;h=fb4208fe2fd4b7361069d5c91296190966283eff;hp=6898541fead2e43ea066cd8a4388ead2f20991a1;hb=659cbbc13f413ed0c5dacd4d03060f48eb500011;hpb=a60001ec86527115ce6e12de65e072299044274a diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index 6898541f..fb4208fe 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -1,4 +1,4 @@ - +
The comments will also help justify the intent of the code. If the comment describes something different than what the code @@ -155,21 +155,21 @@ WIDTH="100%" >
/* if page size greater than 1k ... */ -if ( page_length() > 1024 ) -{ - ... "block" the page up ... -} +> /* 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 ) -{ - ... "block" the page up ... -} + /* if page size is small, send it in blocks */ + 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.
/********************************************************************* - * This will stand out clearly in your code! - *********************************************************************/ -if ( this_variable == that_variable ) -{ - do_something_very_important(); -} +> /********************************************************************* + * This will stand out clearly in your code! + *********************************************************************/ + if (this_variable == that_variable) + { + do_something_very_important(); + } -/* unfortunately, this may not */ -if ( this_variable == that_variable ) -{ - do_something_very_important(); -} + /* unfortunately, this may not */ + if (this_variable == that_variable) + { + do_something_very_important(); + } -if ( this_variable == that_variable ) /* this may not either */ -{ - do_something_very_important(); -}
/********************************************************************* - * This will stand out clearly in your code, - * But the second example won't. - *********************************************************************/ -if ( this_variable == this_variable ) -{ - do_something_very_important(); -} +> /********************************************************************* + * This will stand out clearly in your code, + * But the second example won't. + *********************************************************************/ + if (this_variable == this_variable) + { + do_something_very_important(); + } -if ( this_variable == this_variable ) /*can you see me?*/ -{ - do_something_very_important(); /*not easily*/ -} + if (this_variable == this_variable) /*can you see me?*/ + { + do_something_very_important(); /*not easily*/ + } -/********************************************************************* - * But, the encouraged exceptions: - *********************************************************************/ -int urls_read = 0; /* # of urls read + rejected */ -int urls_rejected = 0; /* # of urls rejected */ + /********************************************************************* + * But, the encouraged exceptions: + *********************************************************************/ + int urls_read = 0; /* # of urls read + rejected */ + int urls_rejected = 0; /* # of urls rejected */ -if ( 1 == X ) -{ - do_something_very_important(); -} + if (1 == X) + { + do_something_very_important(); + } -short do_something_very_important( - short firstparam, /* represents something */ - short nextparam /* represents something else */ ) -{ - ...code here... + short do_something_very_important( + short firstparam, /* represents something */ + short nextparam /* represents something else */ ) + { + ...code here... -} /* -END- do_something_very_important */
if ( 1 == X ) -{ - do_something_very_important(); - ...some long list of commands... -} /* -END- if x is 1 */ +> if (1 == X) + { + do_something_very_important(); + ...some long list of commands... + } /* -END- if x is 1 */ -or: + or: -if ( 1 == X ) -{ - do_something_very_important(); - ...some long list of commands... -} /* -END- if ( 1 == X ) */
int ms_iis5_hack = 0;int ms_iis5_hack = 0;
int msiis5hack = 0; int msIis5Hack = 0;int msiis5hack = 0; int msIis5Hack = 0; |
int load_some_file( struct client_state *csp )int load_some_file(struct client_state *csp)
int loadsomefile( struct client_state *csp ) -int loadSomeFile( struct client_state *csp )int loadsomefile(struct client_state *csp) + int loadSomeFile(struct client_state *csp) |
(.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)
(.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 }; -(#define) : #define DEFAULT_SIZE 100;(enumeration) : enum Boolean {FALSE, TRUE}; + (#define) : #define DEFAULT_SIZE 100;
#define FEATURE_FORCE 1 +> #define FEATURE_FORCE 1 -#ifdef FEATURE_FORCE -#define FORCE_PREFIX blah -#endif /* def FEATURE_FORCE */
#define USE_IMAGE_LIST 1#define USE_IMAGE_LIST 1
#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 UseImageList 1#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 UseImageList 1 |
if ( this == that ) -{ - ... -}if (this == that) + { + ... + }
if ( this == that ) { ... }
if (this == that) { ... }or
if ( this == that ) { ... }
if (this == that) { ... }while ( more lines are read ) -{ - /* Please document what is/is not a comment line here */ - if ( it's a comment ) continue; +> while (more lines are read) + { + /* Please document what is/is not a comment line here */ + if (it's a comment) continue; - do_something( line ); -}
if ( this == that ) -{ - do_something(); - do_something_else(); -}if (this == that) + { + do_something(); + do_something_else(); + }
if ( this == that ) do_something(); do_something_else();
if (this == that) do_something(); do_something_else();or
if ( this == that ) do_something();
if (this == that) do_something();structure->flag = ( condition );structure->flag = (condition);
if ( condition ) { structure->flag = 1; } else { +>if (condition) { structure->flag = 1; } else { structure->flag = 0; }
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 )int first_value = 0; + int some_value = 0; + int another_value = 0; + int this_variable = 0;
a_struct->a_member; -a_struct.a_member; -function_name();a_struct->a_member; + a_struct.a_member; + function_name();
int function1( ... ) -{ - ...code... - return( ret_code ); +> int function1( ... ) + { + ...code... + return(ret_code); -} /* -END- function1 */ + } /* -END- function1 */ -int function2( ... ) -{ -} /* -END- function2 */
int function1( ... ) { ...code... return( ret_code ); } int +>int function1( ... ) { ...code... return(ret_code); } int function2( ... ) { }
static const char * const url_code_map[256] = -{ - NULL, ... -}; +> static const char * const url_code_map[256] = + { + NULL, ... + }; -int function1( ... ) -{ - if ( 1 ) - { - return( ALWAYS_TRUE ); - } - else - { - return( HOW_DID_YOU_GET_HERE ); - } + int function1( ... ) + { + if (1) + { + return ALWAYS_TRUE; + } + else + { + return HOW_DID_YOU_GET_HERE; + } - return( NEVER_GETS_HERE ); + return NEVER_GETS_HERE; -}
short a_short = 0; -float a_float = 0; -struct *ptr = NULL;short a_short = 0; + float a_float = 0; + struct *ptr = NULL;
should_we_block_this(); -contains_an_image(); -is_web_page_blank();should_we_block_this(); + contains_an_image(); + is_web_page_blank();
for ( size_t cnt = 0; cnt < block_list_length(); cnt++ ) -{ - .... -}for (size_t cnt = 0; cnt < block_list_length(); cnt++) + { + .... + }
size_t len = block_list_length(); +> size_t len = block_list_length(); -for ( size_t cnt = 0; cnt < len; cnt++ ) -{ - .... -}
I could then not use it to compare argv's in main: int main( - int argc, const char *argv[] ) { strcmp( argv[0], "privoxy" - ); }
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.
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 )
#include <iostream.h> /* This is not a local include */ -#include "config.h" /* This IS a local include */#include <iostream.h> /* This is not a local include */ + #include "config.h" /* This IS a local include */
/* This is not a local include, but requires a path element. */ -#include <sys/fileName.h>/* This is not a local include, but requires a path element. */ + #include <sys/fileName.h> |
#ifndef PROJECT_H_INCLUDED -#define PROJECT_H_INCLUDED - ... -#endif /* ndef PROJECT_H_INCLUDED */#ifndef PROJECT_H_INCLUDED + #define PROJECT_H_INCLUDED + ... + #endif /* ndef PROJECT_H_INCLUDED */
#ifdef __cplusplus -extern "C" -{ -#endif /* def __cplusplus */ +> #ifdef __cplusplus + extern "C" + { + #endif /* def __cplusplus */ -... function definitions here ... + ... function definitions here ... -#ifdef __cplusplus -} -#endif /* def __cplusplus */
/********************************************************************* - * We're avoiding an include statement here! - *********************************************************************/ -struct file_list; -extern file_list *xyz;/********************************************************************* + * We're avoiding an include statement here! + *********************************************************************/ + struct file_list; + extern file_list *xyz;
switch( hash_string( cmd ) ) -{ - case hash_actions_file : - ... code ... - break; +> switch (hash_string(cmd)) + { + case hash_actions_file: + ... code ... + break; - case hash_confdir : - ... code ... - break; + case hash_confdir: + ... code ... + break; - default : - log_error( ... ); - ... anomaly code goes here ... - continue; / break; / exit( 1 ); / etc ... + default: + log_error( ... ); + ... anomaly code goes here ... + continue; / break; / exit( 1 ); / etc ... -} /* end switch( hash_string( cmd ) ) */
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?
long a = 0; -long b = 0; -long c = 0;long a = 0; + long b = 0; + long c = 0;
If a function creates a struct and stores a pointer to it in a -list, then it should definitely be allocated via `malloc'.If a function creates a struct and stores a pointer to it in a + list, then it should definitely be allocated via `malloc'.
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) { ... }
4.7.10. "Uncertain" new code and/or changes to - existing code, use FIXME or XXX4.7.9. "Uncertain" new code and/or changes to + existing code, use XXX
/* 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...
const char FILENAME_rcs[] = "$Id$"; -/********************************************************************* - * - * File : $Source$ - * - * Purpose : (Fill me in with a good description!) - * - * Copyright : Written by and Copyright (C) 2001-2009 - * the Privoxy team. http://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 - * - *********************************************************************/ +> /********************************************************************* + * + * 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 + * + *********************************************************************/ -#include "config.h" + #include "config.h" - ...necessary include files for us to do our work... + ...necessary include files for us to do our work... -const char FILENAME_h_rcs[] = FILENAME_H_VERSION;
#ifndef _FILENAME_H -#define _FILENAME_H -#define FILENAME_H_VERSION "$Id$" -/********************************************************************* - * - * File : $Source$ - * - * Purpose : (Fill me in with a good description!) - * - * Copyright : Written by and Copyright (C) 2001-2009 - * the Privoxy team. http://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 - * - *********************************************************************/ +> #ifndef _FILENAME_H + #define _FILENAME_H + /********************************************************************* + * + * 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 + * + *********************************************************************/ -#include "project.h" + #include "project.h" -#ifdef __cplusplus -extern "C" { -#endif + #ifdef __cplusplus + extern "C" { + #endif - ... function headers here ... + ... function headers here ... -/* Revision control strings from this header and associated .c file */ -extern const char FILENAME_rcs[]; -extern const char FILENAME_h_rcs[]; + /* Revision control strings from this header and associated .c file */ + extern const char FILENAME_rcs[]; + extern const char FILENAME_h_rcs[]; -#ifdef __cplusplus -} /* extern "C" */ -#endif + #ifdef __cplusplus + } /* extern "C" */ + #endif -#endif /* ndef _FILENAME_H */ + #endif /* ndef _FILENAME_H */ -/* - Local Variables: - tab-width: 3 - end: -*/
/********************************************************************* - * - * Function : FUNCTION_NAME - * - * Description : (Fill me in with a good description!) - * - * parameters : - * 1 : param1 = pointer to an important thing - * 2 : x = pointer to something else - * - * Returns : 0 => Ok, everything else is an error. - * - *********************************************************************/ -int FUNCTION_NAME( void *param1, const char *x ) -{ - ... - return( 0 ); +> /********************************************************************* + * + * Function : FUNCTION_NAME + * + * Description : (Fill me in with a good description!) + * + * parameters : + * 1 : param1 = pointer to an important thing + * 2 : x = pointer to something else + * + * Returns : 0 => Ok, everything else is an error. + * + *********************************************************************/ + int FUNCTION_NAME(void *param1, const char *x) + { + ... + return 0; -}