From 91c21a4be259f911f284a0fd6732786ff764256a Mon Sep 17 00:00:00 2001 From: jongfoster Date: Sun, 24 Feb 2002 14:25:06 +0000 Subject: [PATCH] Formatting changes. Now changing the doctype to DocBook XML 4.1 will work - no other changes are needed. --- doc/source/developer-manual.sgml | 337 ++++++++++++++++--------------- 1 file changed, 170 insertions(+), 167 deletions(-) diff --git a/doc/source/developer-manual.sgml b/doc/source/developer-manual.sgml index a2430d27..ddce0f55 100644 --- a/doc/source/developer-manual.sgml +++ b/doc/source/developer-manual.sgml @@ -1,13 +1,12 @@ - + Documentation Guidelines - All docs are in SGML format and located in the doc/source directory. - - - How do you update the webserver (i.e. the pages on sourceforge)? - - - Run make dok (which uses the documents in doc/source to update all - text files in doc/text and to update + All docs are in SGML format and located in the doc/source directory. + + + How do you update the webserver (i.e. the pages on sourceforge)? + + + Run make dok (which uses the documents in doc/source to update all + text files in doc/text and to update all web documents in doc/webserver. - - - Run make webserver which copies all files from + + + Run make webserver which copies all files from doc/webserver to the sourceforge webserver via scp. - - - + + + - - + + Coding Guidelines @@ -110,7 +109,7 @@ via scp. Comment, Comment, Comment - Explanation: + Explanation: Comment as much as possible without commenting the obvious. For example do not comment "aVariable is equal to bVariable". @@ -125,7 +124,7 @@ via scp. If the comment describes something different than what the code is doing then maybe a programming error is occurring. - Example: + Example: /* if page size greater than 1k ... */ if ( PageLength() > 1024 ) @@ -149,7 +148,7 @@ is actually being done. Use blocks for comments - Explanation: + Explanation: Comments can help or they can clutter. They help when they are differentiated from the code they describe. One line @@ -157,7 +156,7 @@ is actually being done. and the code. Block identifiers do, by surrounding the code with a clear, definable pattern. - Example: + Example: /********************************************************************* * This will stand out clearly in your code! @@ -180,7 +179,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ DoSomethingVeryImportant(); } - Exception: + Exception: If you are trying to add a small logic comment and do not wish to "disrubt" the flow of the code, feel free to use a 1 @@ -192,7 +191,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ Keep Comments on their own line - Explanation: + Explanation: It goes back to the question of readability. If the comment is on the same line as the code it will be harder to read than @@ -203,7 +202,7 @@ if ( thisVariable == thatVariable ) /* this may not either */ at the end of closing braces, when used to comment parameters. - Example: + Example: /********************************************************************* * This will stand out clearly in your code, @@ -233,8 +232,8 @@ if ( 1 == X ) short DoSomethingVeryImportant( - short firstParam, /* represents something */ - short nextParam /* represents something else */ ) + short firstparam, /* represents something */ + short nextparam /* represents something else */ ) { ...code here... @@ -245,7 +244,7 @@ short DoSomethingVeryImportant( Comment each logical step - Explanation: + Explanation: Logical steps should be commented to help others follow the intent of the written code and comments will make the code more @@ -265,7 +264,7 @@ short DoSomethingVeryImportant( Comment All Functions Thoroughly - Explanation: + Explanation: A reader of the code should be able to look at the comments just prior to the beginning of a function and discern the @@ -287,7 +286,7 @@ short DoSomethingVeryImportant( Comment at the end of braces if the content is more than one screen length - Explanation: + Explanation: Each closing brace should be followed on the same line by a comment that describes the origination of the brace if the @@ -301,7 +300,7 @@ short DoSomethingVeryImportant( use following a closing brace: } /* -END- if() or while () or etc... */ - Example: + Example: if ( 1 == X ) { @@ -327,7 +326,7 @@ if ( 1 == X ) Variable Names - Explanation: + Explanation: Use all lowercase, and seperate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C @@ -336,11 +335,11 @@ if ( 1 == X ) template, class, true, false, ...). This is in case we ever decide to port JunkBuster to C++. - Example: + Example: int ms_iis5_hack = 0; - Instead of: + Instead of: @@ -354,7 +353,7 @@ int msiis5hack = 0; int msIis5Hack = 0; Function Names - Explanation: + Explanation: Use all lowercase, and seperate words via an underscore ('_'). Do not start an identifier with an underscore. (ANSI C @@ -363,11 +362,11 @@ int msiis5hack = 0; int msIis5Hack = 0; template, class, true, false, ...). This is in case we ever decide to port JunkBuster to C++. - Example: + Example: int load_some_file( struct client_state *csp ) - Instead of: + Instead of: @@ -382,18 +381,18 @@ int loadSomeFile( struct client_state *csp ) Header file prototypes - Explanation: + 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: + Example: (.h) extern int load_aclfile( struct client_state *csp ); (.c) int load_aclfile( struct client_state *csp ) - Instead of: + Instead of: (.h) extern int load_aclfile( struct client_state * ); or (.h) extern int load_aclfile(); @@ -407,22 +406,22 @@ int loadSomeFile( struct client_state *csp ) Enumerations, and #defines - Explanation: + 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: + Example: (enumeration) : enum Boolean { FALSE, TRUE }; (#define) : #define DEFAULT_SIZE 100; - Note: We have a standard naming scheme for #defines + 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: + Example: #define FEATURE_FORCE 1 @@ -435,7 +434,7 @@ int loadSomeFile( struct client_state *csp ) Constants - Explanation: + Explanation: Spell common words out entirely (do not remove vowels). @@ -445,11 +444,11 @@ int loadSomeFile( struct client_state *csp ) Use underscore (_) to separate adjacent acronyms and abbreviations. Never terminate a name with an underscore. - Example: + Example: #define USE_IMAGE_LIST 1 - Instead of: + Instead of: @@ -473,7 +472,7 @@ int loadSomeFile( struct client_state *csp ) Put braces on a line by themselves. - Explanation: + 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 @@ -481,14 +480,14 @@ int loadSomeFile( struct client_state *csp ) easier to identify the opening and closing braces for a block. - Example: + Example: if ( this == that ) { ... } - Instead of: + Instead of: if ( this == that ) { ... } @@ -496,15 +495,15 @@ if ( this == that ) if ( this == that ) { ... } - Note: In the special case that the if-statement is + Note: In the special case that the if-statement is inside a loop, and it is trivial, i.e. it tests for a condidtion 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-discrection. + Status: developer-discrection. - Example exception: + Example exception: while ( more lines are read ) { @@ -520,13 +519,13 @@ while ( more lines are read ) ALL control statements should have a block - Explanation: + 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: + Example: if ( this == that ) { @@ -534,7 +533,7 @@ if ( this == that ) DoSomethingElse(); } - Instead of: + Instead of: if ( this == that ) DoSomething(); DoSomethingElse(); @@ -542,7 +541,7 @@ if ( this == that ) if ( this == that ) DoSomething(); - Note: The first example in "Instead of" will execute + 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 "feature". The "explanation" and "exception" from the point @@ -555,16 +554,16 @@ if ( this == that ) Do not belabor/blow-up boolean expressions - Example: + Example: structure->flag = ( condition ); - Instead of: + Instead of: if ( condition ) { structure->flag = 1; } else { structure->flag = 0; } - Note: The former is readable and consice. The later + Note: The former is readable and consice. 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 I do not offend by that last comment ... 8-) @@ -576,12 +575,12 @@ structure->flag = ( condition ); Use white space freely because it is free - Explanation: + Explanation: Make it readable. The notable exception to using white space freely is listed in the next guideline. - Example: + Example: int firstValue = 0; int someValue = 0; @@ -598,7 +597,7 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) Don't use white space around structure operators - Explanation: + Explanation: - structure pointer operator ( "->" ) - member operator ( "." ) - functions and parentheses @@ -608,13 +607,13 @@ firstValue = oldValue + ( ( someValue - anotherValue ) - whatever ) connection between the object and variable/function name is not as clear. - Example: + Example: aStruct->aMember; aStruct.aMember; FunctionName(); - Instead of: aStruct -> aMember; aStruct . aMember; + Instead of: aStruct -> aMember; aStruct . aMember; FunctionName (); @@ -624,7 +623,7 @@ FunctionName(); Make the last brace of a function stand out - Example: + Example: int function1( ... ) { @@ -639,12 +638,12 @@ int function2( ... ) } /* -END- function2 */ - Instead of: + Instead of: int function1( ... ) { ...code... return( retCode ); } int function2( ... ) { } - Note: Use 1 blank line before the closing brace and 2 + Note: Use 1 blank line before the closing brace and 2 lines afterwards. This makes the end of function standout to the most casual viewer. Although function comments help seperate functions, this is still a good coding practice. In @@ -652,7 +651,7 @@ int function2( ... ) "do" loops, and long if {} statements too. After all whitespace is free! - Status: developer-discrection on the number of blank + Status: developer-discrection on the number of blank lines. Enforced is the end of function comments. @@ -661,14 +660,14 @@ int function2( ... ) Use 3 character indentions - Explanation: + Explanation: If some use 8 character TABs and some use 3 character TABs, the code can look *very* ragged. So use 3 character indentions only. If you like to use TABs, pass your code through a filter such as "expand -t3" before checking in your code. - Example: + Example: static const char * const url_code_map[256] = { @@ -702,25 +701,25 @@ int function1( ... ) Initialize all variables - Explanation: + Explanation: Do not assume that the variables declared will not be used until after they have been assigned a value somewhere else in the code. Remove the chance of accidentally using an unassigned variable. - Example: + Example: short anShort = 0; float aFloat = 0; struct *ptr = NULL; - Note: It is much easier to debug a SIGSEGV if the + 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-discrection if and only if the + Status: developer-discrection if and only if the variable is assigned a value "shortly after" declaration. @@ -734,12 +733,12 @@ struct *ptr = NULL; Name functions that return a boolean as a question. - Explanation: + Explanation: Value should be phrased as a question that would logically be answered as a true or false statement - Example: + Example: ShouldWeBlockThis(); ContainsAnImage(); @@ -751,7 +750,7 @@ IsWebPageBlank(); Always specify a return type for a function. - Explanation: + Explanation: The default return for a function is an int. To avoid ambiguity, create a return for a function when the return has a @@ -765,19 +764,19 @@ IsWebPageBlank(); Minimize function calls when iterating by using variables - Explanation: + Explanation: It is easy to write the following code, and a clear argument can be made that the code is easy to understand: - Example: + Example: -for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) +for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) { .... } - Note: Unfortunately, this makes a function call for + 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 @@ -791,16 +790,16 @@ for ( size_t cnt = 0; cnt < blockListLength(); cnt ++ ) assign the value to a variable, and evaluate using the variable. - Example: + Example: size_t len = blockListLength(); -for ( size_t cnt = 0; cnt < len; cnt ++ ) +for ( size_t cnt = 0; cnt < len; cnt ++ ) { .... } - Exceptions: if the value of blockListLength() *may* + Exceptions: if the value of blockListLength() *may* change or could *potentially* change, then you must code the function call in the for/while loop. @@ -810,7 +809,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Pass and Return by Const Reference - Explanation: + Explanation: This allows a developer to define a const pointer and call your function. If your function does not have the const @@ -831,7 +830,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Pass and Return by Value - Explanation: + Explanation: Most structures cannot fit onto a normal stack entry (i.e. they are not 4 bytes or less). Aka, a function declaration @@ -847,7 +846,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Names of include files - Explanation: + Explanation: Your include statements should contain the file name without a path. The path should be listed in the Makefile, using -I as @@ -856,13 +855,13 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) partial path to distinguish their header files from system or other header files. - Example: + Example: #include <iostream.h> /* This is not a local include */ #include "config.h" /* This IS a local include */ - Exception: + Exception: @@ -871,7 +870,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) - Note: Please! do not add "-I." to the Makefile + Note: Please! do not add "-I." to the Makefile without a _very_ good reason. This duplicates the #include "file.h" behaviour. @@ -882,7 +881,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Provide multiple inclusion protection - Explanation: + Explanation: Prevents compiler and linker errors resulting from redefinition of items. @@ -892,7 +891,7 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) with your file name, with "." Changed to "_", and make it uppercase. - Example: + Example: #ifndef PROJECT_H_INCLUDED #define PROJECT_H_INCLUDED @@ -904,13 +903,13 @@ for ( size_t cnt = 0; cnt < len; cnt ++ ) Use `extern "C"` when appropriate - Explanation: + 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: + Example: #ifdef __cplusplus extern "C" @@ -929,13 +928,13 @@ extern "C" Where Possible, Use Forward Struct Declaration Instead of Includes - Explanation: + Explanation: Useful in headers that include pointers to other struct's. Modifications to excess header files may cause needless compiles. - Example: + Example: /********************************************************************* * We're avoiding an include statement here! @@ -943,12 +942,12 @@ extern "C" struct file_list; extern file_list *xyz; - Note: If you declare "file_list xyz;" (without the + 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 unneccessary. - Status: Use with discrection. + Status: Use with discrection. @@ -960,7 +959,7 @@ extern file_list *xyz; Turn on warnings - Explanation + Explanation Compiler warnings are meant to help you find bugs. You should turn on as many as possible. With GCC, the switch is @@ -973,14 +972,14 @@ extern file_list *xyz; Provide a default case for all switch statements - Explanation: + 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: + Example: switch( hash_string( cmd ) ) { @@ -999,17 +998,17 @@ switch( hash_string( cmd ) ) } /* end switch( hash_string( cmd ) ) */ - Note: If you already have a default condition, you + 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 + Another Note: This is not so much a readability issue as a robust programming issue. The "anomly 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. + Status: Programmer discretion is advised. @@ -1018,7 +1017,7 @@ switch( hash_string( cmd ) ) Try to avoid falling through cases in a switch statement. - Explanation: + Explanation: In general, you will want to have a 'break' statement within each 'case' of a switch statement. This allows for the code to @@ -1043,12 +1042,12 @@ switch( hash_string( cmd ) ) Use 'long' or 'short' Instead of 'int' - Explanation: + 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 + 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" @@ -1060,7 +1059,7 @@ switch( hash_string( cmd ) ) Don't mix size_t and other types - Explanation: + Explanation: The type of size_t varies across platforms. Do not make assumptions about whether it is signed or unsigned, or about @@ -1076,33 +1075,33 @@ switch( hash_string( cmd ) ) Declare each variable and struct on its own line. - Explanation: + Explanation: It can be tempting to declare a series of variables all on one line. Don't. - Example: + Example: long a = 0; long b = 0; long c = 0; - Instead of: + Instead of: long a, b, c; - Explanation: - there is more room for comments on the + 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 + 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 their functions. - Status: developer-discrection. + Status: developer-discrection. @@ -1110,7 +1109,7 @@ long c = 0; Use malloc/zalloc sparingly - Explanation: + Explanation: Create a local stuct (on the stack) if the variable will live and die within the context of one function call. @@ -1118,7 +1117,7 @@ long c = 0; Only "malloc" a struct (on the heap) if the variable's life will extend beyond the context of one function call. - Example: + Example: If a function creates a struct and stores a pointer to it in a list, then it should definately be allocated via `malloc'. @@ -1129,7 +1128,7 @@ list, then it should definately be allocated via `malloc'. The Programmer Who Uses 'malloc' is Responsible for Ensuring 'free' - Explanation: + Explanation: If you have to "malloc" an instance, you are responsible for insuring that the instance is `free'd, even if the deallocation @@ -1139,18 +1138,18 @@ list, then it should definately be allocated via `malloc'. "good thing (tm)". You may need to offer a free/unload/destuctor type function to accomodate this. - Example: + Example: int load_re_filterfile( struct client_state *csp ) { ... } static void unload_re_filterfile( void *f ) { ... } - Exceptions: + Exceptions: The developer cannot be expected to provide `free'ing functions for C run-time library functions ... such as `strdup'. - Status: developer-discrection. The "main" use of this + Status: developer-discrection. The "main" use of this standard is for allocating and freeing data structures (complex or nested). @@ -1161,13 +1160,13 @@ static void unload_re_filterfile( void *f ) { ... } Add loaders to the `file_list' structure and in order - Explanation: + 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 + 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. @@ -1179,7 +1178,7 @@ static void unload_re_filterfile( void *f ) { ... } "Uncertain" new code and/or changes to exitinst code, use FIXME - Explanation: + Explanation: If you have enough confidence in new code or confidence in your changes, but are not *quite* sure of the reprocussions, @@ -1199,7 +1198,7 @@ static void unload_re_filterfile( void *f ) { ... } /* FIXME: new code that *may* break something else... */ ...new code here... - Note: If you make it clear that this may or may not + 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 conversly exclude from the project). @@ -1212,9 +1211,9 @@ static void unload_re_filterfile( void *f ) { ... } Addendum: Template for files and function comment blocks: - Example for file comments: + Example for file comments: -const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:48 swa Exp $"; +const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.5 2001/10/31 18:16:51 swa Exp $"; /********************************************************************* * * File : $Source$ @@ -1259,22 +1258,22 @@ const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:4 const char FILENAME_h_rcs[] = FILENAME_H_VERSION; - Note: This declares the rcs variables that should be + 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 + Note: The formfeed character that is present right after the comment flower box is handy for (X|GNU)Emacs users to skip the verbige 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 file header comments: #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.4 2001/09/23 10:13:48 swa Exp $" +#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.5 2001/10/31 18:16:51 swa Exp $" /********************************************************************* * * File : $Source$ @@ -1339,7 +1338,7 @@ extern const char FILENAME_h_rcs[]; */ - Example for function comments: + Example for function comments: /********************************************************************* * @@ -1347,7 +1346,7 @@ extern const char FILENAME_h_rcs[]; * * Description : (Fill me in with a good description!) * - * Parameters : + * parameters : * 1 : param1 = pointer to an important thing * 2 : x = pointer to something else * @@ -1362,7 +1361,7 @@ int FUNCTION_NAME( void *param1, const char *x ) } - Note: If we all follow this practice, we should be + Note: If we all follow this practice, we should be able to parse our code to create a "self-documenting" web page. @@ -1387,29 +1386,29 @@ why you did it. Explain release numbers. major, minor. developer releases. etc. - - + + Remove any existing rpm with rpm -e - - + + Remove any file that was left over. This includes (but is not limited to) - - /var/log/junkbuster - /etc/junkbuster - /usr/sbin/junkbuster - /etc/init.d/junkbuster - /usr/doc/junkbuster* - - - + + /var/log/junkbuster + /etc/junkbuster + /usr/sbin/junkbuster + /etc/init.d/junkbuster + /usr/doc/junkbuster* + + + Install the rpm. Any error messages? - - start,stop,status junkbuster with the specific script + + start,stop,status junkbuster with the specific script (e.g. /etc/rc.d/init/junkbuster stop). Reboot your machine. Does - autostart work? - Start browsing. Does the junkbuster work? Logfile written? - Remove the rpm. Any error messages? All files removed? - + autostart work? + Start browsing. Does the junkbuster work? Logfile written? + Remove the rpm. Any error messages? All files removed? + @@ -1418,15 +1417,15 @@ Install the rpm. Any error messages? Please submit test reports only with the test form at sourceforge. Three simple steps: - - - Select category: the distribution you test on. - Select group: the version of Junkbuster that we are about to release. - Fill the Summary and Detailed Description with something - intelligent (keep it short and precise). - - - Do not mail to the mailinglist (we cannot keep track on issues there). + + + Select category: the distribution you test on. + Select group: the version of Junkbuster that we are about to release. + Fill the Summary and Detailed Description with something + intelligent (keep it short and precise). + + + Do not mail to the mailinglist (we cannot keep track on issues there). @@ -1471,6 +1470,10 @@ at sourceforge. Three simple steps: Temple Place - Suite 330, Boston, MA 02111-1307, USA. $Log: developer-manual.sgml,v $ + Revision 1.5 2001/10/31 18:16:51 swa + documentation added: howto generate docs in text and html + format, howto move stuff to the webserver. + Revision 1.4 2001/09/23 10:13:48 swa upload process established. run make webserver and the documentation is moved to the webserver. documents -- 2.39.2