TITLE="Documentation Guidelines"
HREF="documentation.html"><LINK
REL="NEXT"
-TITLE="Version Control Guidelines"
-HREF="cvs.html"><LINK
+TITLE="Testing Guidelines"
+HREF="testing.html"><LINK
REL="STYLESHEET"
TYPE="text/css"
HREF="../p_doc.css"></HEAD
ALIGN="right"
VALIGN="bottom"
><A
-HREF="cvs.html"
+HREF="testing.html"
>Next</A
></TD
></TR
CLASS="SECT1"
><A
NAME="CODING"
->5. Coding Guidelines</A
+>4. Coding Guidelines</A
></H1
><DIV
CLASS="SECT2"
CLASS="SECT2"
><A
NAME="S1"
->5.1. Introduction</A
+>4.1. Introduction</A
></H2
><P
>This set of standards is designed to make our lives easier. It is
CLASS="SECT2"
><A
NAME="S2"
->5.2. Using Comments</A
+>4.2. Using Comments</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S3"
->5.2.1. Comment, Comment, Comment</A
+>4.2.1. Comment, Comment, Comment</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S4"
->5.2.2. Use blocks for comments</A
+>4.2.2. Use blocks for comments</A
></H3
><P
><I
></P
><P
>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
+ wish to "disrupt" the flow of the code, feel free to use a 1
line comment which is NOT on the same line as the code.</P
></DIV
><DIV
CLASS="SECT3"
><A
NAME="S5"
->5.2.3. Keep Comments on their own line</A
+>4.2.3. Keep Comments on their own line</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S6"
->5.2.4. Comment each logical step</A
+>4.2.4. Comment each logical step</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S7"
->5.2.5. Comment All Functions Thoroughly</A
+>4.2.5. Comment All Functions Thoroughly</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S8"
->5.2.6. Comment at the end of braces if the
+>4.2.6. Comment at the end of braces if the
content is more than one screen length</A
></H3
><P
CLASS="SECT2"
><A
NAME="S9"
->5.3. Naming Conventions</A
+>4.3. Naming Conventions</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S10"
->5.3.1. Variable Names</A
+>4.3.1. Variable Names</A
></H3
><P
><I
>Explanation:</I
></P
><P
->Use all lowercase, and seperate words via an underscore
+>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.
CLASS="SECT3"
><A
NAME="S11"
->5.3.2. Function Names</A
+>4.3.2. Function Names</A
></H3
><P
><I
>Explanation:</I
></P
><P
->Use all lowercase, and seperate words via an underscore
+>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.
CLASS="SECT3"
><A
NAME="S12"
->5.3.3. Header file prototypes</A
+>4.3.3. Header file prototypes</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S13"
->5.3.4. Enumerations, and #defines</A
+>4.3.4. Enumerations, and #defines</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S14"
->5.3.5. Constants</A
+>4.3.5. Constants</A
></H3
><P
><I
CLASS="SECT2"
><A
NAME="S15"
->5.4. Using Space</A
+>4.4. Using Space</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S16"
->5.4.1. Put braces on a line by themselves.</A
+>4.4.1. Put braces on a line by themselves.</A
></H3
><P
><I
>Note:</I
> 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,
+ condition 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.</P
><P
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection.</P
+> developer-discretion.</P
><P
><I
CLASS="EMPHASIS"
CLASS="SECT3"
><A
NAME="S17"
->5.4.2. ALL control statements should have a
+>4.4.2. ALL control statements should have a
block</A
></H3
><P
CLASS="SECT3"
><A
NAME="S18"
->5.4.3. Do not belabor/blow-up boolean
+>4.4.3. Do not belabor/blow-up boolean
expressions</A
></H3
><P
><I
CLASS="EMPHASIS"
>Note:</I
-> The former is readable and consice. The later
+> The former is readable and concise. 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-)</P
CLASS="SECT3"
><A
NAME="S19"
->5.4.4. Use white space freely because it is
+>4.4.4. Use white space freely because it is
free</A
></H3
><P
CLASS="SECT3"
><A
NAME="S20"
->5.4.5. Don't use white space around structure
+>4.4.5. Don't use white space around structure
operators</A
></H3
><P
CLASS="SECT3"
><A
NAME="S21"
->5.4.6. Make the last brace of a function stand
+>4.4.6. Make the last brace of a function stand
out</A
></H3
><P
CLASS="EMPHASIS"
>Note:</I
> Use 1 blank line before the closing brace and 2
- lines afterwards. This makes the end of function standout to
+ lines afterward. 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
+ separate functions, this is still a good coding practice. In
fact, I follow these rules when using blocks in "for", "while",
"do" loops, and long if {} statements too. After all whitespace
is free!</P
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection on the number of blank
+> developer-discretion on the number of blank
lines. Enforced is the end of function comments.</P
></DIV
><DIV
CLASS="SECT3"
><A
NAME="S22"
->5.4.7. Use 3 character indentions</A
+>4.4.7. Use 3 character indentions</A
></H3
><P
><I
CLASS="SECT2"
><A
NAME="S23"
->5.5. Initializing</A
+>4.5. Initializing</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S24"
->5.5.1. Initialize all variables</A
+>4.5.1. Initialize all variables</A
></H3
><P
><I
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection if and only if the
+> developer-discretion if and only if the
variable is assigned a value "shortly after" declaration.</P
></DIV
></DIV
CLASS="SECT2"
><A
NAME="S25"
->5.6. Functions</A
+>4.6. Functions</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S26"
->5.6.1. Name functions that return a boolean as a
+>4.6.1. Name functions that return a boolean as a
question.</A
></H3
><P
CLASS="SECT3"
><A
NAME="S27"
->5.6.2. Always specify a return type for a
+>4.6.2. Always specify a return type for a
function.</A
></H3
><P
CLASS="SECT3"
><A
NAME="S28"
->5.6.3. Minimize function calls when iterating by
+>4.6.3. Minimize function calls when iterating by
using variables</A
></H3
><P
CLASS="SECT3"
><A
NAME="S29"
->5.6.4. Pass and Return by Const Reference</A
+>4.6.4. Pass and Return by Const Reference</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S30"
->5.6.5. Pass and Return by Value</A
+>4.6.5. Pass and Return by Value</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S31"
->5.6.6. Names of include files</A
+>4.6.6. Names of include files</A
></H3
><P
><I
>Note:</I
> Please! do not add "-I." to the Makefile
without a _very_ good reason. This duplicates the #include
- "file.h" behaviour.</P
+ "file.h" behavior.</P
></DIV
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S32"
->5.6.7. Provide multiple inclusion
+>4.6.7. Provide multiple inclusion
protection</A
></H3
><P
CLASS="SECT3"
><A
NAME="S33"
->5.6.8. Use `extern "C"` when appropriate</A
+>4.6.8. Use `extern "C"` when appropriate</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S34"
->5.6.9. Where Possible, Use Forward Struct
+>4.6.9. Where Possible, Use Forward Struct
Declaration Instead of Includes</A
></H3
><P
> 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.</P
+ file is unnecessary.</P
><P
><I
CLASS="EMPHASIS"
>Status:</I
-> Use with discrection.</P
+> Use with discretion.</P
></DIV
></DIV
><DIV
CLASS="SECT2"
><A
NAME="S35"
->5.7. General Coding Practices</A
+>4.7. General Coding Practices</A
></H2
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S36"
->5.7.1. Turn on warnings</A
+>4.7.1. Turn on warnings</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S37"
->5.7.2. Provide a default case for all switch
+>4.7.2. Provide a default case for all switch
statements</A
></H3
><P
default :
log_error( ... );
- ... anomly code goes here ...
+ ... anomaly code goes here ...
continue; / break; / exit( 1 ); / etc ...
} /* end switch( hash_string( cmd ) ) */</PRE
CLASS="EMPHASIS"
>Another Note:</I
> This is not so much a readability issue
- as a robust programming issue. The "anomly code goes here" may
+ as a robust programming issue. The "anomaly 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.</P
><P
CLASS="SECT3"
><A
NAME="S38"
->5.7.3. Try to avoid falling through cases in a
+>4.7.3. Try to avoid falling through cases in a
switch statement.</A
></H3
><P
CLASS="SECT3"
><A
NAME="S39"
->5.7.4. Use 'long' or 'short' Instead of
+>4.7.4. Use 'long' or 'short' Instead of
'int'</A
></H3
><P
CLASS="SECT3"
><A
NAME="S40"
->5.7.5. Don't mix size_t and other types</A
+>4.7.5. Don't mix size_t and other types</A
></H3
><P
><I
CLASS="SECT3"
><A
NAME="S41"
->5.7.6. Declare each variable and struct on its
+>4.7.6. Declare each variable and struct on its
own line.</A
></H3
><P
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection.</P
+> developer-discretion.</P
></DIV
><DIV
CLASS="SECT3"
CLASS="SECT3"
><A
NAME="S42"
->5.7.7. Use malloc/zalloc sparingly</A
+>4.7.7. Use malloc/zalloc sparingly</A
></H3
><P
><I
>Explanation:</I
></P
><P
->Create a local stuct (on the stack) if the variable will
+>Create a local struct (on the stack) if the variable will
live and die within the context of one function call.</P
><P
>Only "malloc" a struct (on the heap) if the variable's life
><PRE
CLASS="PROGRAMLISTING"
>If a function creates a struct and stores a pointer to it in a
-list, then it should definately be allocated via `malloc'.</PRE
+list, then it should definitely be allocated via `malloc'.</PRE
></TD
></TR
></TABLE
CLASS="SECT3"
><A
NAME="S43"
->5.7.8. The Programmer Who Uses 'malloc' is
+>4.7.8. The Programmer Who Uses 'malloc' is
Responsible for Ensuring 'free'</A
></H3
><P
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/destuctor type function to accomodate this.</P
+ free/unload/destuctor type function to accommodate this.</P
><P
><I
CLASS="EMPHASIS"
><I
CLASS="EMPHASIS"
>Status:</I
-> developer-discrection. The "main" use of this
+> developer-discretion. The "main" use of this
standard is for allocating and freeing data structures (complex
or nested).</P
></DIV
CLASS="SECT3"
><A
NAME="S44"
->5.7.9. Add loaders to the `file_list' structure
+>4.7.9. Add loaders to the `file_list' structure
and in order</A
></H3
><P
CLASS="SECT3"
><A
NAME="S45"
->5.7.10. "Uncertain" new code and/or changes to
- exitinst code, use FIXME</A
+>4.7.10. "Uncertain" new code and/or changes to
+ existing code, use FIXME</A
></H3
><P
><I
></P
><P
>If you have enough confidence in new code or confidence in
- your changes, but are not *quite* sure of the reprocussions,
+ your changes, but are not *quite* sure of the repercussions,
add this:</P
><P
>/* FIXME: this code has a logic error on platform XYZ, *
- attempthing to fix */ #ifdef PLATFORM ...changed code here...
+ attempting to fix */ #ifdef PLATFORM ...changed code here...
#endif</P
><P
>or:</P
>Note:</I
> 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
+ include in the project (or conversely exclude from the
project).</P
></DIV
></DIV
CLASS="SECT2"
><A
NAME="S46"
->5.8. Addendum: Template for files and function
+>4.8. Addendum: Template for files and function
comment blocks:</A
></H2
><P
><TD
><PRE
CLASS="PROGRAMLISTING"
->const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $";
+>const char FILENAME_rcs[] = "$Id: developer-manual.sgml,v 1.45 2002/05/19 23:01:54 hal9 Exp $";
/*********************************************************************
*
* File : $Source$
>Note:</I
> 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
+ skip the verbiage and get to the heart of the code (via
`forward-page' and `backward-page'). Please include it if you
can.</P
><P
CLASS="PROGRAMLISTING"
>#ifndef _FILENAME_H
#define _FILENAME_H
-#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.27 2002/04/08 15:31:18 hal9 Exp $"
+#define FILENAME_H_VERSION "$Id: developer-manual.sgml,v 1.45 2002/05/19 23:01:54 hal9 Exp $"
/*********************************************************************
*
* File : $Source$
ALIGN="right"
VALIGN="top"
><A
-HREF="cvs.html"
+HREF="testing.html"
>Next</A
></TD
></TR
WIDTH="33%"
ALIGN="right"
VALIGN="top"
->Version Control Guidelines</TD
+>Testing Guidelines</TD
></TR
></TABLE
></DIV