X-Git-Url: http://www.privoxy.org/gitweb/?a=blobdiff_plain;ds=sidebyside;f=doc%2Fwebserver%2Fdeveloper-manual%2Fcoding.html;h=c0fbcaa5a22a85011f6da95f769c47f9b0ec7204;hb=1c4bd7276a5f733e283c0484803bfca670f76654;hp=0855d86fe202819be5cc71a2912e52106b323250;hpb=69b45dc21f48175fb34a8e1e2f45d46870e37941;p=privoxy.git diff --git a/doc/webserver/developer-manual/coding.html b/doc/webserver/developer-manual/coding.html index 0855d86f..c0fbcaa5 100644 --- a/doc/webserver/developer-manual/coding.html +++ b/doc/webserver/developer-manual/coding.html @@ -1,97 +1,106 @@ - - + -
-This set of standards is designed to make our lives easier. It is - developed with the simple goal of helping us keep the "new and improved - Privoxy" consistent and reliable. Thus - making maintenance easier and increasing chances of success of the - project.
- -And that of course comes back to us as individuals. If we can - increase our development and product efficiencies then we can solve - more of the request for changes/improvements and in general feel good - about ourselves. ;->
+ +Explanation:
- -Comment as much as possible without commenting the obvious. 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 or explanation would have - prevented the extra research. Please help your brother IJB'ers - out!
- -The comments will also help justify the intent of the code. If the - comment describes something different than what the code is doing - then maybe a programming error is occurring.
- -Example:
- -
- + |
+
Explanation:
- -Use all lowercase, and separate words via an underscore ('_'). Do - not start an identifier with an underscore. (ANSI C reserves these - for use by the compiler and system headers.) Do not use identifiers - which are reserved in ANSI C++. (E.g. template, class, true, false, - ...). This is in case we ever decide to port Privoxy to C++.
- -Example:
- -
- + |
+
Explanation:
- -The brace needs to be on a line all by itself, not at the end of - the statement. Curly braces should line up with the construct that - they're associated with. This practice makes it easier to identify - the opening and closing braces for a block.
- -Example:
- -
- -if ( this == that ) + |
+
+ 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:
- -What you think is guaranteed is never really guaranteed. The value - that you don't think you need to check is the one that someday will - be passed. So, to protect yourself from the unknown, always have a - default step in a switch statement.
- -Example:
- -
- -switch( hash_string( cmd ) ) + |
+
+ Explanation: +
++ 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. +
++ Example: +
+
++int load_re_filterfile(struct client_state *csp) { ... } +static void unload_re_filterfile(void *f) { ... } ++ |
+
+ 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 it should come first. +
++ Explanation: +
++ If you have enough confidence in new code or confidence in your + changes, but are not *quite* sure of the repercussions, add this: +
++ /* XXX: this code has a logic error on platform XYZ, * attempting + to fix */ #ifdef PLATFORM ...changed code here... #endif +
++ or: +
++ /* XXX: I think the original author really meant this... */ + ...changed code here... +
++ or: +
++ /* 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 project). +
+Explanation:
- -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.
- -Example:
- ++ Example for file + comments: +
- -int load_re_filterfile( struct client_state *csp ) { ... } -static void unload_re_filterfile( void *f ) { ... } -- |
-
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 it should come first.
-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, * - attempting to fix */ #ifdef PLATFORM ...changed code here... - #endif
- -or:
- -/* FIXME: I think the original author really meant this... */ - ...changed code here...
- -or:
- -/* FIXME: 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 project).
-Example for file - comments:
- -
- -const char FILENAME_rcs[] = "$Id$"; ++const char FILENAME_rcs[] = "$I<!-- Break CVS Substitution -->d$"; /********************************************************************* * - * File : $Source$ + * File : $S<!-- Break CVS Substitution -->ource$ * * Purpose : (Fill me in with a good description!) * * Copyright : Written by and Copyright (C) 2001-2009 - * the Privoxy team. http://www.privoxy.org/ + * 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 @@ -1460,40 +1594,42 @@ const char FILENAME_rcs[] = "$Id$"; const char FILENAME_h_rcs[] = FILENAME_H_VERSION;- |
-
Note: This - declares the rcs variables that should be added to the - "show-proxy-args" 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:
- -
- + |
+
+ Note: This + declares the rcs variables that should be added to the + "show-proxy-args" 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: +
+
+#ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id$" +#define FILENAME_H_VERSION "$I<!-- Break CVS Substitution -->d$" /********************************************************************* * - * File : $Source$ + * File : $S<!-- Break CVS Substitution -->ource$ * * Purpose : (Fill me in with a good description!) * * Copyright : Written by and Copyright (C) 2001-2009 - * the Privoxy team. http://www.privoxy.org/ + * 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 @@ -1543,17 +1679,17 @@ extern const char FILENAME_h_rcs[]; end: */- |
-
Example for function - comments:
- -
- + |
+
+ Example for function + comments: +
+
+/********************************************************************* * * Function : FUNCTION_NAME @@ -1567,48 +1703,51 @@ extern const char FILENAME_h_rcs[]; * Returns : 0 => Ok, everything else is an error. * *********************************************************************/ -int FUNCTION_NAME( void *param1, const char *x ) +int FUNCTION_NAME(void *param1, const char *x) { ... - return( 0 ); + return 0; }+ |
+
+ Note: If we + all follow this practice, we should be able to parse our code to + create a "self-documenting" web page. +
+