From 86916307c081c899bcfafb8da55f8ed010fa2969 Mon Sep 17 00:00:00 2001 From: jongfoster Date: Mon, 10 Sep 2001 18:37:48 +0000 Subject: [PATCH] Changes discussed in my e-mail of 10/9/01 - mainly typos and minor corrections, but also added "extern C" and "-Wall" sections --- doc/STANDARDS.txt | 139 +++++++++++++++++++++++++--------------------- 1 file changed, 77 insertions(+), 62 deletions(-) diff --git a/doc/STANDARDS.txt b/doc/STANDARDS.txt index c30f8dbc..705c33b4 100644 --- a/doc/STANDARDS.txt +++ b/doc/STANDARDS.txt @@ -215,7 +215,12 @@ if ( 1 == X ) @@@ Explanation: -Seperate words via an underscore ('_'). +Use all lowercase, and seperate 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 JunkBuster to C++. @@@ Example: @@ -231,16 +236,21 @@ int msIis5Hack = 0; @@@ Explanation: -Seperate words via an underscore ('_'). +Use all lowercase, and seperate 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 JunkBuster to C++. @@@ Example: -int load_aclfile( struct client_state *csp ) +int load_some_file( struct client_state *csp ) @@@ Instead of: -int loadaclfile( struct client_state *csp ) -int loadAclFile( struct client_state *csp ) +int loadsomefile( struct client_state *csp ) +int loadSomeFile( struct client_state *csp ) @@ Header file prototypes @@ -262,35 +272,30 @@ that you use in the c file. (.c) int load_aclfile( struct client_state *csp ) -18. Ennumerations, and #defines +@@ Enumerations, and #defines @@@ 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: (enumeration) : enum Boolean { FALSE, TRUE }; (#define) : #define DEFAULT_SIZE 100; -@@@ Note: We should have a standard naming scheme for Symbols that -toggle a feature in the precompiler, and the constants used by that -feature. I'd propose that the toggles should be just one word, with -a common prefix, and that any depandant constants should be -prefixed by that word. - -The prefix could be WITH_, HAVE_, ENABLE_, FEATURE_ etc. - -@@@ Status: I see some this in the code currently! Anybody "figured" -out a standard way to do this? +@@@ Note: We have a standard naming scheme for #defines that +toggle a feature in the preprocessor: FEATURE_xxx, where +xxx is a short (preferably 1 or 2 word) description. @@@ Example: -#define ENABLE_FORCE 1 +#define FEATURE_FORCE 1 -#ifdef ENABLE_FORCE +#ifdef FEATURE_FORCE #define FORCE_PREFIX blah -#endif /* def ENABLE_FORCE */ +#endif /* def FEATURE_FORCE */ @@ Constants @@ -694,15 +699,37 @@ Prevents compiler and linker errors resulting from redefinition of items. Wrap each header file with the following syntax to prevent multiple -inclusions of the file. Of course, replace FILENAME_UPPERCASE with +inclusions of the file. Of course, replace PROJECT_H with your file name, with "." Changed to "_", and make it uppercase. @@@ Example: -#ifndef _PROJECT_H -#define _PROJECT_H - ... -#endif /* ndef _PROJECT_H */ +#ifndef PROJECT_H_INCLUDED +#define PROJECT_H_INCLUDED + ... +#endif /* ndef PROJECT_H_INCLUDED */ + + +@@ Use `extern "C"` when appropriate + +@@@ 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: + +#ifdef __cplusplus +extern "C" +{ +#endif /* def __cplusplus */ + +... function definitions here ... + +#ifdef __cplusplus +} +#endif /* def __cplusplus */ @@ Where Possible, Use Forward Struct Declaration Instead of Includes @@ -730,6 +757,15 @@ prototype a pointer, however, the header file is unneccessary. @ General Coding Practices +@@ Turn on warnings + +@@@ Explanation + +Compiler warnings are meant to help you find bugs. You should turn +on as many as possible. With GCC, the switch is "-Wall". Try and +fix as many warnings as possible. + + @@ Provide a default case for all switch statements @@@ Explanation: @@ -804,6 +840,17 @@ equivalence ... I forget the exact typedefs now). Should we add these to IJB now that we have a "configure" script? +@@ Don't mix size_t and other types + +@@@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. + + @@ Declare each variable and struct on its own line. @@@ Explanation: @@ -924,10 +971,10 @@ thing (tm)", it will be easier to identify and include in the project @@@ Example for file comments: -const char FILENAME_rcs[] = "$Id: STANDARDS.txt,v 1.3 2001/07/02 01:50:04 iwanttokeepanon Exp $"; +const char FILENAME_rcs[] = "$Id: STANDARDS.txt,v 1.4 2001/07/13 01:27:19 iwanttokeepanon Exp $"; /********************************************************************* * - * File : $Source: /cvsroot/ijbswa/current/doc/STANDARDS.txt,v $ + * File : $Source$ * * Purpose : (Fill me in with a good description!) * @@ -957,23 +1004,7 @@ const char FILENAME_rcs[] = "$Id: STANDARDS.txt,v 1.3 2001/07/02 01:50:04 iwantt * Temple Place - Suite 330, Boston, MA 02111-1307, USA. * * Revisions : - * $Log: STANDARDS.txt,v $ - * Revision 1.3 2001/07/02 01:50:04 iwanttokeepanon - * A modified STANDARDS.txt file. I removed my XEmacs test lines (commited in v1.2) - * and made the file Outline-mode compatible. I used "@" for my header lines instead - * of "*" (which interfered in some C comments). I also removed the formfeed character - * from the `outline-regexp' variable because it interfered with the "H" file header and - * the "C" file header comments. - * - * All of the "stardards points/issues" are still available for discussion, cussing, - * and/or flaming . - * - * Revision 1.2 2001/06/28 04:02:42 iwanttokeepanon - * Testing XEmacs and VC/CVS modes. Will this work? We shall see... - * - * Revision 1.1 2001/06/28 03:01:32 iwanttokeepanon - * A suggested standard for IJB. Outline-mode formatting and spell checking to follow. Developer comments encouraged and requested. - * + * $Log$ * *********************************************************************/ @@ -999,10 +1030,10 @@ and get to the heart of the code (via `forward-page' and #ifndef _FILENAME_H #define _FILENAME_H -#define FILENAME_H_VERSION "$Id: STANDARDS.txt,v 1.3 2001/07/02 01:50:04 iwanttokeepanon Exp $" +#define FILENAME_H_VERSION "$Id: STANDARDS.txt,v 1.4 2001/07/13 01:27:19 iwanttokeepanon Exp $" /********************************************************************* * - * File : $Source: /cvsroot/ijbswa/current/doc/STANDARDS.txt,v $ + * File : $Source$ * * Purpose : (Fill me in with a good description!) * @@ -1032,23 +1063,7 @@ and get to the heart of the code (via `forward-page' and * Temple Place - Suite 330, Boston, MA 02111-1307, USA. * * Revisions : - * $Log: STANDARDS.txt,v $ - * Revision 1.3 2001/07/02 01:50:04 iwanttokeepanon - * A modified STANDARDS.txt file. I removed my XEmacs test lines (commited in v1.2) - * and made the file Outline-mode compatible. I used "@" for my header lines instead - * of "*" (which interfered in some C comments). I also removed the formfeed character - * from the `outline-regexp' variable because it interfered with the "H" file header and - * the "C" file header comments. - * - * All of the "stardards points/issues" are still available for discussion, cussing, - * and/or flaming . - * - * Revision 1.2 2001/06/28 04:02:42 iwanttokeepanon - * Testing XEmacs and VC/CVS modes. Will this work? We shall see... - * - * Revision 1.1 2001/06/28 03:01:32 iwanttokeepanon - * A suggested standard for IJB. Outline-mode formatting and spell checking to follow. Developer comments encouraged and requested. - * + * $Log$ * *********************************************************************/ -- 2.39.2