@@@ 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:
@@@ 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
(.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
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
@ 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:
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:
@@@ 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!)
*
* 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
#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!)
*
* 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