\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 #include #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 $ \\ {\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}