\subsection{Choosing Names}

Names should be meaningful. Abbreviations should also be meaningful, and
should be chosen by some uniform, rational scheme. 

\begin{itemize}

\item Each variable and name must have the same usage and meaning
throughout the program. 

\item Names should not be re-defined in inner blocks.  Nor should global
names be redeclared within a function. 

\item Standard meaningful names for local (temporary) variables include:
\begin{vsetoff} \begin{tabbing}
{\tt p, q, a, b}	\= character \kill	\\
{\tt i, j, k}		\> indexes		\\
{\tt c, ch}		\> character		\\
{\tt n, m}		\> counters		\\
{\tt p, q, a, b}	\> pointers		\\
{\tt s}			\> strings		\\
\end{tabbing} \end{vsetoff}

Never use the letter \verb'l' as a variable or in any context where it
could be confused with the digit \verb'1'.
\end{itemize}
\subsection{Names for \NAME{struct}, \NAME{union}, and
{\tt \char"23 define}s} 

Consider using \NAME{typedef}{} for \NAME{struct}{} and \NAME{union}{}
declarations. This helps both reader of the code and type checking
programs such as \NAME{lint}.

If a declaration is complex, use \NAME{typdef}{} declarations to
build it up out of separate parts.\footnote{Suggestion courtesy
of Morris Keesan (\verb'keesan@BBN-UNIX.ARPA'.}
For example, instead of writing
\begin{vsetoff} \begin{verbatim}
/*
 * Array of 15 pointers to functions returning integers
 */
int (*(apfi[15]))();
\end{verbatim} \end{vsetoff}
you can construct the definition piece-by-piece as
\begin{vsetoff} \begin{verbatim}
typedef int IntFunc();          /* Function return int  */
typedef IntFunc *PtrToIntFunc;  /* Pointer to int func  */
PtrToIntFunc apf[15];           /* Array of func ptrs   */
\end{verbatim} \end{vsetoff}

In a large system, global names should be composed of two parts, a one
or two letter prefix, relating to the sub-system, and a longer name
defining the item itself.

If a several symbols are needed to refer to an entity, they should
have some consistent relation.  For example:
\begin{vsetoff}  \begin{verbatim}
#define MAX_ITEM  123

typedef struct ITEM {
    struct ITEM *it_next;
    int         it_value;
} ITEM;

ITEM item_store[MAX_ITEM];
ITEM *it_first = &item_store[0];
#define ITEM_LAST (&item_store[MAX_ITEM])
\end{verbatim} \end{vsetoff}

Note that For a member of a \NAME{struct}, the prefix should be related
to the body of the \NAME{struct}{} name.

If structures are declared in \verb'#include' files and there is a risk
that the file might be included twice, you should block multiple
compilation to prevent compiler error messages.  For example, if the
{\tt ITEM} structure declaration were stored in a header file, item.h, you
should write it as follows:
\begin{vsetoff}  \begin{verbatim}
#ifndef item_h
typedef struct ITEM {
    ...
} ITEM;
#define item_h 1                /* ITEM now declared    */
#endif
\end{verbatim} \end{vsetoff}

\subsection{Pointers}

Pointers should be declared and used as ``pointer to a thing of type
X''. Do not, for example, use a variable which is declared as ``pointer
to \NAME{int}'' to point to a \NAME{char}, even though the particular
compiler and/or machine will let you do it.  On most compilers,
\NAME{union}{} declarations s may be used to allow pointers to different
objects.  At other times, explicit type casts are the simplest solution.

For example, a print formatter may need both types of pointer:
\begin{vsetoff}  \begin{verbatim}
#define     INT  0              /* Storage classes for  */
#define    LONG  1              /* Formatter            */
#define     NEG  2              /* Negative flag        */

typedef struct FORMAT {
    char   f_type;              /* Format type          */
    int    f_width;             /* Item storage width   */
    int    f_radix;             /* Conversion radix     */
} FORMAT;

static FORMAT formatinfo[] {
    { 'd',  INT, 10 },
    { 'o',  INT,  8 },
    { 'u',  INT, 10 },
    { 'D', LONG, 10 },
    { EOS,    0,  0 },
};

c_doprnt(format, argp, fildes)
char    *format;
int     *argp;
FILE    *fildes;
{
    register union {
        FORMAT  *fmt;           /* -> format codes      */
        char    *out;           /* -> result            */
    } p;                        /* General pointer      */
    int radix;                  /* Conversion radix     */
    int temp;                   /* General temp value   */
    char        c;              /* Current format char  */
    long        value;          /* Value to convert     */
    char        work[WORKSIZE]; /* Number buffer        */
    ...
    /*
     * Search for a matching format.
     */
    p.fmt = formatinfo;
    while (p.fmt->f_type != c && p.fmt->f_type != EOS))
        p.fmt++;
    if (p.fmt->f_type != EOS) {
        /*
         * A numeric conversion was found.  Get the
         * value and expand it into the work area.
         */
        radix = p.fmt->f_radix;
        temp = p.fmt->f_width;
        p.out = &work[WORKSIZE - 1];
        *p.out = EOS;           /* Terminate result     */
        if (temp == INT) {
            if (c == 'd' && *argp < 0) {
                value = -(*argp++);
                temp = NEG;     /* Remember signal      */
            }
            else {              /* 'u', 'x', or 'o'     */
                value = (unsigned) *argp++;
            }
        }
        else {          /* Get long from caller */
            value = *((long *) argp)++;
        }
        if (value == 0)
            *--p.out = '0';
        else {
            do {        /* Convert unsigned number != 0 */
                *--p.out = "0123456789abdef"[value%radix];
            } while ((value /= radix) != 0);
            if (temp == NEG)
                *--p.out = '-';
        }
    }
    ...                         /* Other conversions    */
    fputs(p.out, filedes);      /* Output the string    */
    ...
\end{verbatim} \end{vsetoff}

Note that a union was used when the same (\NAME{register}) variable was
used to point to two separate objects (at different points of the
program), while casts were used when a pointer refers to different
objects, depending on the particular data being processed.
Some compilers do not permit a declaration of \NAME{register union},
so you may have to use explicit casts in all cases.

\subsection{Standard Defined-names}

There are a number of \verb'#define''d names whose meaning is standardized
by C programs:
\begin{tabbing}
~~~~ \= {\tt TESTING} \= For comparison or assignment of pointers \+ \kill \\
{\tt TRUE}	\> Boolean true					\\
{\tt FALSE}	\> Boolean false				\\
{\tt NULL}	\> Error return from file routines		\\
{\tt NULLST}	\> For comparison or assignment of pointers	\\
{\tt EOS}	\> The end of string marker			\\
{\tt EOF}	\> End-of-file					\\
~								\\
\< In writing a large program, the following standards proved to be
useful: \\
{\tt DEBUG}	\> Switch for compiling debugging code		\\
{\tt DEBUG\_X}	\> Debug sub-part X only			\\
{\tt TESTING}	\> Compile a built-in test program.  See below.	\\
{\tt INT\_16}	\> A storage integer that must hold 16 bits.	\\
{\tt INT\_32}	\> A storage integer that must hold 32 bits.	\\
{\tt INT}	\> Whatever is fastest for this compiler.	\\
{\tt FLAG}	\> {\tt TRUE/FALSE} (or a small range of values) flag. \\
\end{tabbing}

In developing a large program, many subroutines included a small main
program for testing.  This program was conditionally compiled by
\verb'#define''ing the \verb'TESTING' compile-time variable.  When the
module has been debugged, \verb'TESTING' is undefined and the module
integrated with the rest of the package.

\verb'INT_16', \verb'INT_32', and \verb'INT' were used in the same large
program to eliminate dependency on certain compiler/machine
dependencies.  For example, on the Motorola 68000, 16-bit integers are
computationally faster than the default (32-bit) \NAME{int}, whereas on
the Vax-11, 32-bit integers are more efficient.  The program's header
file thus contained:
\begin{vsetoff}  \begin{verbatim}
#ifdef vax
#define INT_16  short
#define INT_32  int
#define INT     int
#endif
#ifdef M68000
#define INT_16  short
#define INT_32  long
#define INT     short
#endif
\end{verbatim} \end{vsetoff}



\SECT{Portability}

Portability means that a source file can be compiled and executed
on different machines, operating systems, and/or compilers with
either no source file changes or, at most, changes to system-specific
header files.  In writing portable software, the following should be
understood:
\begin{itemize}
\item Most C compilers predefine symbols that may be used to isolate
machine-dependent code.  The following list may be helpful:
\begin{itemize}
\item Decus C defines \verb'pdp11', \verb'decus', \verb'rsx'
(or \verb'rt11').
\item VaxC defines \verb"vax", \verb"vms", and \verb"vax11c"
\item Venix defines \verb"pdp11", and \verb"unix"
\item A compiler for the Dec-20 defines \verb"TOPS20" and \verb"PDP10"
\end{itemize}
When running on Unix, the compiler option \verb'-Dxxx' may be used
to pre-define a symbol without modifying the source code.
(VaxC, version 2.0 provides an equivalent capability).
\item Some things are inherently non-portable.  For example, a hardware
device handler can, in general, not be transported between operating
systems.

\item Different machines have different word sizes.  While the language
standard guarantees that \NAME{long int}{} is at least as long as
\NAME{int}{} and \NAME{short int}{} are never longer than \NAME{int}, it
does not guarantee any specific word length.  Note also that pointers
and integers are not necessarily the same size; nor are all pointers the
same size.

If you are transporting programs where \NAME{int}{} and \NAME{long}{}
sizes differ, be sure to double-check {\tt printf} format statements.
Some {\tt printf} implementations require \verb'%ld' for longs, while others
require \verb'%D'.

\item Word size and constants can interact in unpleasant ways.  For example,
\begin{vsetoff}  \begin{verbatim}
    int x;
    x &= 0177770;
\end{verbatim} \end{vsetoff}
clears the low-order 3 bits of an integer on a PDP-11.  However, on
a Vax, it will also clear the upper half-word.  Instead, you should
use:
\begin{vsetoff}  \begin{verbatim}
    x &= ~07;
\end{verbatim} \end{vsetoff}
Which is portable.
\item Beware of code that presupposes expression evaluation order.
The following sequences should be avoided:
\begin{vsetoff} \begin{verbatim}
value = getchar() + getchar();
value = *p++ + *p++;
*p = *p++;
func(*p++, *p++);
\end{verbatim} \end{vsetoff}
In the above sequences, different compilers will evaluate
the ``side-effects'' in different ways.  Instead, you
can rewrite these as
\begin{vsetoff} \begin{verbatim}
value = getchar(); value += getchar();
value = *p++; value += *p++;
p[1] = *p;  p++;
temp = *p++; func(temp, *p++);
\end{verbatim} \end{vsetoff}
\item Beware of code that takes advantage of two's complement arithmetic.
In particular, optimizations that replace division or multiplication with
shifts should be avoided.
\item Watch out for the PDP-11 signed character, which becomes unsigned on
many other machines.
\item Do not presuppose any specific byte ordering within words.
\item Do not default Boolean tests.  Use
\begin{vsetoff}  \begin{verbatim}
    if (func() != FALSE) {
\end{verbatim} \end{vsetoff}
Instead of
\begin{vsetoff}  \begin{verbatim}
    if (func()) {
\end{verbatim} \end{vsetoff}
A particularily insidious example of incorrect code is:
\begin{vsetoff}  \begin{verbatim}
    if (strcmp(s1, s2)) {
        /* different */
    }
\end{verbatim} \end{vsetoff}
Always write
\begin{vsetoff}  \begin{verbatim}
    if ((strcmp(s1, s2) != 0) {
        /* different */
    }
\end{verbatim} \end{vsetoff}
Decus C provides \verb'streq()' for this purposes.  On other systems, you
can easily write a macro:
\begin{vsetoff}  \begin{verbatim}
    #define STREQ(a, b) (strcmp((a), (b)) == 0)
\end{verbatim} \end{vsetoff}

One counter example to this is generally made for predicates: functions
which have no other purpose than to return {\tt TRUE} or {\tt FALSE},
and which are named so that the meaning of a {\tt TRUE} return is
absolutely obvious. For example, a routine should be named
\verb'isvalid()', not \verb'checkvalid()'. 

\item Be very suspicious of numeric values appearing in the code.
Almost all constants would be better expressed as \verb'#define'd
quantities.

\item Any unsigned type other than \NAME{unsigned int}{} should be
identified by a \NAME{typedef}, as these are highly compiler dependent.
As noted above, large programs should have a central header file which
encapsulates machine-dependent information.

\item Become familiar with the standard library and use it for string
and character manipulation.  Do not reimplement standard routines as the
person reading your code must then figure out whether you're doing
something special in the reimplemented stuff.  Home-brew ``standard''
routines are a fruitful source of bugs as your routines might be called
by other parts of the library.  Also, the standard library hides
non-portable details that you might not (and generally should not) be
aware of.

\end{itemize}

\SECT{Miscellaneous}
This section contains a fairly disorganized list of hints, some of which
appear in other sections of this style sheet.  They are not in any
specific order.
\begin{itemize}
\item Don't change syntax via macro substitution.  It makes the program
unintelligible to all who come after.
\item There is a time and place for embedded assignment statements.  In some
cases, this is the best way to specify the algorithm.  However, it
is not your responsibility to second-guess the compiler by packing
code as tightly as possible.  For example:
\begin{vsetoff}  \begin{verbatim}
    a = b + c;
    d = a + r;
\end{verbatim} \end{vsetoff}
should not be rewritten as:
\begin{vsetoff}  \begin{verbatim}
    d = (a = b + c) + r;
\end{verbatim} \end{vsetoff}
Even though the latter may save one instruction.

Note also that a C compiler may freely modify the order of execution
of an expression.  Thus,
\begin{vsetoff}  \begin{verbatim}
    a = (b + c) + d;
\end{verbatim} \end{vsetoff}
Will not necessarily add b to c, then add the result to d.
If the order of evaluation is important (for accuracy or overflow
prevention), you must write separate statements with temporary
variables:
\begin{vsetoff}  \begin{verbatim}
    temp = b + c;
    a = temp + d;
\end{verbatim} \end{vsetoff}
\item Don't overuse the ternary \verb'(cond) ? a : b' operator
The condition should always be enclosed in parentheses.
Nested ternary operators should be avoided if possible.

The ternary operator does not guarantee order of execution.
The following is therefore unsafe:
\begin{vsetoff}  \begin{verbatim}
    a = (b == 0) ? 0 : d / b;
\end{verbatim} \end{vsetoff}

\item \NAME{goto}{} statements should be used sparingly.  The main place
where they are useful is in breaking out of several levels of
\NAME{switch}/\NAME{for}/\NAME{while}{} nesting.  If a \NAME{goto}{} is
needed, the accompaning label should be at the left margin with a
comment explaining who jumps here. The \NAME{continue}{} statement is also
a source of bugs. 

But, don't be afraid that evil spirits will haunt you if you write the
dreaded \NAME{goto}.  It is often much clearer to use \NAME{goto}
statements to
escape from an inner loop than by using seemingly random combinations of
\NAME{break}, \NAME{continue}, \NAME{return}{} and \NAME{default}{} exits
from \NAME{switch}{} statements. To some extent, the lack of a rich set of
exit operations is a failure of C, requiring discipline and a commitment
to clarity on the part of the programmer.

Often, the need for \NAME{goto} statements
and complicated exit conditions is an
indication that the inner constructions ought to be redone as a separate
function with a success/failure return code.

Never \NAME{goto}{} into an \NAME{else}{} clause or into the body of a
\NAME{for}{} or \NAME{while}{} loop.

\item In declarations (\verb'#define' statements, structure definitions,
or variable defininitions), various components should line up.  Thus: 

\begin{vsetoff}  \begin{verbatim}
#define TESTING    1
#define PRODUCTION 2
\end{verbatim} \end{vsetoff}

\item When the storage structure or type of a variable is important,
always state it explicitly.  In particular, use \NAME{auto}{} if you are
going to use the address of a local variable using \verb'&'.  Declare
integer parameters as \NAME{int}, rather than letting them default.

\item Sometimes it is impossible to avoid doing something tricky.  (And
sometimes you just can't resist the temptation.) At the very least, put
enough documentation in the code to warn the poor soul who comes after
you.

\item Try to write code that is clear and safe, rather than something
that ``seems'' easier to compile.  Make sure local variables are local
(or declared \NAME{static}) so things won't blow up when you compile
with other modules.

\item Try to keep the flow of control through your program apparent.
Where this is governed by separately-compiled tables (such as a
finite-state parser), embed comments in the parser table to aid the
maintainer.

\item Use \NAME{register}{} variables wherever possible.  They are
especially efficient when used as structure or array pointers.  Since
offsets within a structure are known at compile time, the compiler can
generate extremely efficient code. 

For example, suppose a program is processing a collection of elements
which have a value and a set of flag bits.  The ``simple'' solution
would be:
\begin{vsetoff}  \begin{verbatim}
int    value[MAX];
long   flags[MAX];
int    array_max;

int
lookfor(arg_val, arg_flag)
int        arg_val;
long       arg_flag;
/*
 * Return index to the element with the same
 * value and at least one matching flag bit.
 * Return -1 on failure.
 */
{
    int     i;

    for (i = 0; i < array_max; i++) {
        if (value[i] == arg_val
         && (flag[i] & arg_flag) != 0) {
            return (i);
        }
    }
    return (-1);
}
\end{verbatim} \end{vsetoff}
The inner loop of the above requires turning the index \verb'i' into a
pointer twice.  The above should generally be rewritten as:
\begin{vsetoff}  \begin{verbatim}
typedef struct data {
    int     d_value;
    long    d_flag;
} DATA;
DATA        values[MAX];
DATA        *top_value;

DATA *
lookfor(arg_value, arg_flag)
int         arg_value;
long        arg_flag;
/*
 * Return a pointer to the element with the same
 * value and at least one matching flag bit.
 * Return NULL on failure.
 */
{
    register DATA       *dp;

    for (dp = &values[0]; dp < top_value; dp++) {
        if (dp->d_value == arg_value
         && (dp->d_flag & arg_flag) != 0) {
            return (dp);
        }
    }
    return (NULLST);
}
\end{verbatim} \end{vsetoff}
Note the use of redundant braces in the above programs.

\item If a function manipulates a database stored in a separate file,
the routines that manipulate (generate and access) this database should
be isolated from other routines.  The internal structure of the data
base should also be defined.  If the database format is likely to
change, a release date or version should be buried in the database and
precompiled into the manager software.  The program should check the
validity of the release date when the package opens the database.

\item If a file contains the main routine of a program, that should be
the first function in the file.  On Unix and VMS, where programs may be
called as sub-processes, it is important that all programs exit by
calling \verb"exit()".  On Unix, use \verb"exit(0)" for success and
\verb"exit(1)" for failure.  The following construction may be useful:
\begin{vsetoff}  \begin{verbatim}
#ifdef vms
#include        <ssdef.h>
#include        <stsdef.h>
#define IO_NORMAL (SS$_NORMAL | STS$M_INHIB_MSG)
#define IO_ERROR  (SS$_ABORT)
#endif
#ifndef IO_NORMAL
#define IO_NORMAL       0
#endif
#ifndef IO_ERROR
#define IO_ERROR        1
#endif
...
    exit(IO_NORMAL);        /* Normal program exit  */
    exit(IO_ERROR);         /* Failure program exit */
\end{verbatim} \end{vsetoff}

\item In the condition portion of an
\NAME{if}, \NAME{for}, \NAME{while}, etc., side effects
whose effect extends beyond the extent of the guarded statement block
should be avoided.  For example, consider:
\begin{vsetoff}  \begin{verbatim}
    if ((c = getchar()) != EOF) {       
        /* guarded-statements */
     }
    /* other-statements */
\end{verbatim} \end{vsetoff}

It is natural to think of variable \verb"c" being ``bound'' to a value
only within ``guarded-statements.''  Its value should not be presumed
upon entrance to ``other-statements.''  Using a variable set or modified
inside a condition outside the range of statements guarded by the
condition is in general quite distracting.

\item You should not use \verb'||' and \verb'&&' with right-hand
operands having side-effects.  For example,
\begin{vsetoff}  \begin{verbatim}
    if ((fildes = fopen("file.nam", "r")) == NULL
     || readin(fildes) != SUCCESS) {
        bug("something's wrong somewhere.);
    }
\end{verbatim} \end{vsetoff}
A better approach would be
\begin{vsetoff}  \begin{verbatim}
    if ((fildes = fopen("file.nam", "r")) == NULL) {
        perror("file.nam");
        bug("Can't open input file");
    }
    else if (readin(fildes) != SUCCESS) {
        perror("file.nam");
        bug("couldn't read file");
    }
\end{verbatim} \end{vsetoff}
Whenever conditional sequences contain both \verb'||' and \verb'&&',
parentheses should be used for clarity.

\item Routines should be kept reasonably short.  It is important for the
maintainer to be able to read and comprehend all of the routine at one
glance.  In general, a routine processes one or more inputs and
generates one or more outputs, where each of the inputs and outputs can
be consisely described.

Signs that a routine is too long, and ought to be split up, are: length
greater than 100 lines (two pages), heavy use of localized variables
(whose active scope is less than the entire routine), or conditional or
loop statements nested more than four levels.

Even when processing is linear (do first part, do second part, etc.), it
is often helpful to the maintainer to break the routine into separate
pieces:
\begin{vsetoff}  \begin{verbatim}
main(argc, argv)
int       argc;
char      *argv[];
{
    setup(argc, argv);
    process();   
    finish();
}
\end{verbatim} \end{vsetoff}

On many operating systems, the setup() and finish() modules can be
compiled into overlay structures, leaving more room for in-memory data.
\item Use of globals should be minimized by judicious use of parameters.

\item In general, a routine should be designed with a ``natural,''
easy to remember calling sequence.  Routines with more than five
arguments are not recommended. Routines with ``op-code'' arguments,
where one argument determines the interpretation, type, and functions of
the others, are also not recommended (though they often prove useful as
internal routines to a package, they should {\it not} be part of a
package's documented interface.)

\item Datatype compatibility should be practiced where possible.  This
can be facilitated by use of C's \NAME{typedef}{} facility, by explicit
type casting, or by the use of the \NAME{union}{} datatype.

A package which returns a pointer to a structure whose format need not
be known outside of that package may return a ``generic pointer''
\verb'(char *)'.  The C language specifically guarantees that any
pointer may be converted to a \verb'char *' and back again without harm.

\item Use \verb'#define' statements to eliminate magic numbers. 
Use compile-time computation to combine magic numbers into others:
\begin{vsetoff}  \begin{verbatim}
#define ARRAY_A_SIZE 123
#define ARRAY_B_SIZE 456
#define BOTH_SIZE (ARRAY_A_SIZE + ARRAY_B_SIZE)
\end{verbatim} \end{vsetoff}

If you change \verb'ARRAY_A_SIZE', the compiler with change
\verb'BOTH_SIZE' without your further intervention.

\item Some experience is needed to decide what to put in a \NAME{for}{}
statement and what to put in the loop body.  In general, you should put
what is needed to control the loop in the
\NAME{for}{} statement, and the process itself in
the body.  Also, you should be disciplined about using
\NAME{break}, \NAME{continue},
and \NAME{goto}{} to control "unusual" break-out cases.  For example, the
following code searches a symbol table for an unused element:
\begin{vsetoff}  \begin{verbatim}
    for (sp = &sym[0]; sp < &sym[MAX_SYM]; sp++) {
        if ((sp->sy_flag & UNUSED) != 0)
            goto found;
    }
    error_message("No room in symbol table");
    return (FALSE);

found:
    /* ... here to process symbol                   */
return (TRUE);
\end{verbatim} \end{vsetoff}
In this case, the most natural way to write the code is to use a
\NAME{goto}{}
for the "normal" case.  While the above could be handled by a flag (or
auxiliary test), the solution seems less intuitive:
\begin{vsetoff}  \begin{verbatim}
    for (sp = &sym[0]; sp < &sym[MAX_SYM]; sp++) {
        if ((sp->sy_flag & UNUSED) != 0)
            break;
    }
    if (sp >= &sym[MAX_SYM]) {
        error_message("No room in symbol table");
        return (FALSE);
    }
    else {
        /* ... here to process symbol               */
        return (TRUE);
    }
\end{verbatim} \end{vsetoff}
\item The first three register variables, in lexicographic order, should
be ones for which the most gain can be gotten.

\item While C distinguishes between upper- and lower-case in variables
and keywords, the programmer should maintain disipline.  Global symbols
should never require case distinction as they will not work properly on
many operating systems.  You should also avoid using the same name for
different quantities.

Never require the reader to see differences between ``\verb'1'''
(digit), ``\verb'l''' (letter), and ``\verb'I'''; or between
``\verb'O''', ``\verb'Q''', and ``\verb'0'''. The C language ``long
constant'' identifier (``\verb'1l''' is a long integer if the second
character is the letter ``\verb'L''') offers a good example of a
practice to avoid (use ``\verb'1L''' instead).

\end{itemize}


\SECT{Re-examining Braces and Indentation}
Several other style sheets recommend the brace syntax:
\begin{vsetoff}  \begin{verbatim}
    if (cond)
    {
        statements;
    }
\end{verbatim} \end{vsetoff}
Another recommendation is similar to the above except that the
braces are aligned with the conditionally-executed statements:
\begin{vsetoff}  \begin{verbatim}
    if (cond)
        {
        statements;
        }
\end{verbatim} \end{vsetoff}
This follows the structured programming methodology that ``begin'' and
``end'' are at the same indentation level.

The syntax recommended in this manual (with the left brace on the same
line as the conditional) seems, in the author's eyes, to bind the left
brace closer to the conditional than does the ``left brace on a new
line'' format.  Also, Left braces don't appear in the same column as
right braces and are, hence, more visually distinctive.  Finally, the
right brace is aligned vertically with the clause introducer (\NAME{if},
\NAME{while}, etc.) with no intruding text.  This seems to make things
more visible. 

When an early draft of this style sheet was reviewed, a collegue, Jeff
Lomicka, took exception to the recommendations for indentation.

Here is an alternative indentation style presented with its own
rationale.  You may choose your style accordingly, but be prepared to
understand and defend your choice.

A program is a sequential execution of simpler functions, each of which
is broken up into more primitive functions until the primitives become
directly executable.  A compound statement is the same kind of entity as
is a single statement or a function call, and should therefore be
treated equally.

The goal of proper indentation is to separate visually the level of
detail at which the program is viewed, and to permit the reader easily
to associate related elements of the program with each other.  For
example, we need to associate an \NAME{if}{} with its \NAME{else}, and to
be able to determine what are the contents of the \NAME{if}-clause and
\NAME{else}-clause.

The general formatting rules are:
\begin{itemize}
\item Statements executed sequentially are all at the same indentation
level.
\item If a statement includes other statements, such the \NAME{while}{} loop
body or the \NAME{then}{} and \NAME{else}{} clauses of a conditional, these
statements are indented to the next block level.

\item Braces are part of the statement, and are always displayed at the
same indentation level as the code they contain.

\item This improves the readability of the program, since each compound
statement easily identified as a primitive function, separate from the
control structure that controls its execution.  In traditional top-down
fashion
\begin{vsetoff}  \begin{verbatim}
    if (conditional)
        statement;
    else
        statement;
\end{verbatim} \end{vsetoff}
is seen when reading a passage of code at one level of detail, and
a close look can reveal the details of the statements:
\begin{vsetoff}  \begin{verbatim}
    if (conditional)
        { /* when executed and what is done here   */
        statements;
        }
    else
        { /* when executed and what is done here   */
        statements;
        }
\end{verbatim} \end{vsetoff}
A reader is therefore not forced to see the inner block details when
trying to understand only the outer block.  Note that when reading the
code at the outer block's level of detail, only the introducing comment
needs to be read to discern the purpose of a compound statement.
\end{itemize}
These rules are modified according to the same considerations as
listed earlier, as seen in the else-if.  For example:
\begin{vsetoff}  \begin{verbatim}
    while (conditional)
        { /* when executed and what is done here       */
        statements;
        }

    for (s1; s2; s3)
        { /* when executed and what is done here       */
        statements;
        }

    if (conditional)
        { /* when executed and what is done here       */
        statements;
        }
    else if (conditional)
        { /* when executed and what is done here       */
        statements;
        }
    else
        { /* when executed and what is done here       */
        statements;
        }
\end{verbatim} \end{vsetoff}
Note how these rules effect switch statements:
\begin{vsetoff}  \begin{verbatim}
    switch (c)
        {
    case 1: /* when executed and what is done here     */
        statements;
        break;
    case 2: /* when executed and what is done here     */
        statements;
        break;
    }
\end{verbatim} \end{vsetoff}
The purpose of a typographical style is to present the semantic
elements of your program in a way that is understandable by your
readers.

The C programming language can be very deceptive.  Although it has every
characteristic of other block structured languages, because of the way
it ``looks'', it must be treated differently.  Many programmers started
their careers using Algol derivatives, such as Simula: languages with
\NAME{BEGIN}{} and \NAME{END}{} statements. In such languages,
\NAME{BEGIN}{} and \NAME{END}{} must be prominant as
any declaration--even a function--could follow any \NAME{BEGIN}.  (Later
versions of C, though not Decus C, permit variables to be declared
following a \verb'{'.) There was thus little difference between
single statements and whole programs.  In these languages, keywords were
always in upper case, library routines would have their first letter
capitalized, and user defined variables and functions were in lower
case.  Everybody did things that way.

While, superficially, C doesn't look very different, it is so in some
deeper sense. Those curly braces look like they want to disappear.  The
blocking appears to want to be done with indentation alone.  Since you
can't see the braces anyway, it probably doesn't make that much
difference where they are, so long as the contents of the blocks are
properly indented.  There doesn't seem to be any real difference in
readability.

Note also that C has at least four separate ``flavors'' of braces:
structure definition delimiters, function delimiters, \NAME{if},
\NAME{for}, \NAME{while}, \NAME{do}, delimiters, and
\NAME{switch} block
delimiters.  Since there is only one construct terminator, \verb'}', it
becomes more important for the reader to be able to scan up and
immediately locate the construct initiator. (In some other languages,
such as Bliss, each construct, such as \NAME{IF}, has an unique
terminator, such as \NAME{FI}. While this helps prevent runaway syntax
errors, it also requires the programmer to remember more information.) 

Responding to the difference in language syntax, programmers develop
different programming habits.  For example, an Algol programmer might
think of an \NAME{IF}{} statement, in general, as:
\begin{vsetoff}  \begin{verbatim}
    IF condition THEN statement ELSE statement;
\end{verbatim} \end{vsetoff}
(with one statement in each clause), while a C programmer might
think of an \NAME{IF}{} statement as:
\begin{vsetoff}  \begin{verbatim}
    IF condition THEN statements ELSE statements END-IF;
\end{verbatim} \end{vsetoff}
Where in C, the \NAME{THEN}{} is implied by the end of the condition, the
braces around the \NAME{THEN}{} clause are a syntatic nusiance, and the
\NAME{END-IF}{} is
represented by the closing brace on the \NAME{ELSE}{} clause.

We can do the same with loops.
\begin{vsetoff}  \begin{verbatim}
    Algol:  WHILE condition DO statement;
    C:      WHILE condition DO statements END-WHILE;
\end{verbatim} \end{vsetoff}
Here too, the patterns we look for when reading the code are different.
The {\tt END-IF} and {\tt END-WHILE} are represented, in C, by
``\verb'}''' which requires typographical prominance and must be kept
visually distinct from the visually similar ``\verb'{'''.  The C style: 
\begin{vsetoff}  \begin{verbatim}
    if (condition) {
        statements;
    }
\end{verbatim} \end{vsetoff}
is thus more understandable.

But, of course, programmers are different in their needs, backgrounds,
and motivations.  Essential, however, is the need to define a style,
understand it, use it, and know when to violate it to attain the
overriding goal of clarity and communication.
\SECT{Summary}
The following extended--and artificial--example shows most of
the recommended decisions.
\begin{tabbing}
\hspace{10em} \= \hspace{32em} \kill
			\> \verb$/*$ \\
			\> \verb$ * A C Style Summary Sheet$ \\
{\it A block comment}	\> \verb$ * abstracted from one$ \\
{\it descirbes a file}	\> \verb$ * by Henry Spencer,$ \\
{\it or section of code.} \> \verb$ * University of Toronto,$ \\
			\> \verb$ * Department of Zoology$ \\
			\> \verb$ */$ \\
			\> \verb$$ \\
{\it Header files}	\> \verb$#include <stdio.h>$ \\
{\it don't nest.}	\> \verb$#include "local.h"$ \\
			\> \verb$ $ \\
{\NAME{typedef} \it and} \> \verb$typedef int     SYTYPE;$ \\
{\it structure definitions.} \> \verb$typedef struct SYMBOL {$ \\
{\it followed by all}	\> \verb$ struct SYMBOL *s_next; /* Link entries  */$ \\
{\it global symbol}	\> \verb$ char  *s_name;         /* Symbol name   */$ \\
{\it definitions.}	\> \verb$ SYTYPE s_type;         /* Symbol type   */$ \\
			\> \verb$#define   TY_UNK 0      /*   unknown     */$ \\
			\> \verb$#define   TY_INT 1      /*   integer     */$ \\
			\> \verb$#define   TY_STR 2      /*   char *      */$ \\
			\> \verb$ union {$ \\
			\> \verb$   int          i;      /* Integer       */$ \\
			\> \verb$   char         *s;     /* String        */$ \\
			\> \verb$ } s_value;             /* Datum         */$ \\
			\> \verb$} SYMBOL;$ \\
{\it Explicit initialization.} \> \verb$SYMBOL  *sy_head = NULL;$ \\
			\> \verb$ $ \\
			\> \verb$/*$ \\
			\> \verb$ * sylookup(text)$ \\
			\> \verb$ *$ \\
			\> \verb$ * Look for a word in the symbol table,$ \\
			\> \verb$ * return a pointer to the symbol if found.$ \\
			\> \verb$ * return NULL if not found.$ \\
			\> \verb$ */$ \\
			\> \verb$$ \\
			\> \verb$static SYMBOL *$ \\
			\> \verb$sylookup(text)$ \\
			\> \verb$char    *text;          /* Symbol name   */$ \\
			\> \verb${$ \\
			\> \verb$    register SYMBOL *syp;$ \\
			\> \verb$$ \\
{\it Note indentation}	\> \verb$    for (syp = sy_head; syp != NULL;$ \\
{\it and use of braces.} \> \verb$            syp = syp->s_next) {$ \\
			\> \verb$        if (strcmp(text, syp->s_name) == 0)$ \\
			\> \verb$            return (syp);$ \\
			\> \verb$    }$ \\
			\> \verb$    return (NULL);$ \\
			\> \verb$}$ \\
			\> \verb$$ \\
			\> \verb$/*$ \\
			\> \verb$ * syprint(text)$ \\
			\> \verb$ *$ \\
			\> \verb$ * If the argument is in the symbol table,$ \\
			\> \verb$ * then print the associated value,$ \\
			\> \verb$ * else print "not found".$ \\
			\> \verb$ */$ \\
			\> \verb$$ \\
			\> \verb$syprint(text)$ \\

			\> \verb$char    *text;          /* Symbol name   */$ \\
			\> \verb${$ \\
			\> \verb$    register SYMBOL     *syp;$ \\
			\> \verb$$ \\
			\> \verb$    printf("%s: ", text);$ \\
{\it An embedded assign-} \> \verb$    if ((syp = sylookup(text)) == NULL) {$ \\
{\it ment statment.}	\> \verb$        printf("%s: not found\n", text);$ \\
{\it Don't default \tt NULL.} \> \verb$    }$ \\
			\> \verb$    else {$ \\
			\> \verb$        switch (syp->s_type) {$ \\
			\> \verb$        case TY_UNK:$ \\
			\> \verb$            printf("unknown");$ \\
			\> \verb$            break;$ \\
			\> \verb$$ \\
			\> \verb$        case TY_INT:$ \\
			\> \verb$            printf("%d", syp->s_value.i);$ \\
			\> \verb$            break;$ \\
			\> \verb$$ \\
			\> \verb$        case TY_STR:$ \\
			\> \verb$            printf("%s", syp->s_value);$ \\
			\> \verb$            break;$ \\
			\> \verb$$ \\
			\> \verb$        default:$ \\
{\it Print a message}	\> \verb$           printf("? unexpected type %d\n",$ \\
{\it before calling}	\> \verb$               syp->s_type);$ \\
{\tt abort().}		\> \verb$            abort();$ \\
			\> \verb$        }$ \\
			\> \verb$    }$ \\
			\> \verb$    printf("\n");$ \\
			\> \verb$}$ \\
\end{tabbing}
\end{document}

