Changes discussed in my e-mail of 10/9/01 - mainly typos and minor

corrections, but also added "extern C" and "-Wall" sections

diff --git a/doc/STANDARDS.txt b/doc/STANDARDS.txt
index c30f8db..705c33b 100644 (file)
--- a/doc/STANDARDS.txt
+++ b/doc/STANDARDS.txt
@@ -215,7 +215,12 @@ if ( 1 == X )
 
 @@@ Explanation:
 
 
 @@@ 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:
 
 
 @@@ Example:
 


@@ -231,16 +236,21 @@ int msIis5Hack = 0;
 
 @@@ Explanation:
 
 
 @@@ 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:
 
 
 @@@ Example:
 

-int load_aclfile( struct client_state *csp )
+int load_some_file( struct client_state *csp )

 
 @@@ Instead of:
 
 
 @@@ 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
 
 
 @@ Header file prototypes


@@ -262,35 +272,30 @@ that you use in the c file.
 (.c) int load_aclfile( struct client_state *csp )
 
 
 (.c) int load_aclfile( struct client_state *csp )
 
 

-18.  Ennumerations, and #defines
+@@  Enumerations, and #defines

 
 @@@ Explanation:
 
 Use all capital letters, with underscores between words.
 
 @@@ 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;
 
 
 @@@ 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:
 
 
 @@@ Example:
 

-#define ENABLE_FORCE 1
+#define FEATURE_FORCE 1

 
 

-#ifdef ENABLE_FORCE
+#ifdef FEATURE_FORCE

 #define FORCE_PREFIX blah
 #define FORCE_PREFIX blah

-#endif /* def ENABLE_FORCE */
+#endif /* def FEATURE_FORCE */

 
 
 @@ Constants
 
 
 @@ 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
 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:
 
 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
 
 
 @@ 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
 
 
 @ 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:
 @@ 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?
 
 
 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:
 @@ 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:
 
 
 @@@ 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        :  $S<!-- Break CVS Substitution -->ource$

  *
  * Purpose     :  (Fill me in with a good description!)
  *
  *
  * 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   :
  *                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 <G>.
- *
- *    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.
- *
+ *    $L<!-- Break CVS Substitution -->og$

  *
  *********************************************************************/
 \f
  *
  *********************************************************************/
 \f


@@ -999,10 +1030,10 @@ and get to the heart of the code (via `forward-page' and
 
 #ifndef _FILENAME_H
 #define _FILENAME_H
 
 #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        :  $S<!-- Break CVS Substitution -->ource$

  *
  * Purpose     :  (Fill me in with a good description!)
  *
  *
  * 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   :
  *                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 <G>.
- *
- *    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.
- *
+ *    $L<!-- Break CVS Substitution -->og$

  *
  *********************************************************************/
 \f
  *
  *********************************************************************/
 \f