http:^^www.cs.wisc.edu^~glew^coding-standards.html

This data set contains WWW-pages collected from computer science departments of various universities

	x[0] = 1;
	x[1] = 1;
	sum = 2;				/* New code. */
	for (i = 2 ; i <= LIMIT ; i++)
		x[i] = ackermann(x, i);
		sum = sum + x[i];		/* New code. */
</PRE>
Here, although the indentation might make it look right,
<CODE>sum</CODE> is only calculated <I>after</I> the <CODE>for</CODE> loop
and would end up with the value, <CODE>2 + ackermann(LIMIT)</CODE>.
While we all know better than to do something stupid like this,
its occurrence (by others, of course) is all too frequent.
Thus the recommended form of the initial construct is:

<PRE>
	x[0] = 1;
	x[1] = 1;
	for (i = 2 ; i <= LIMIT ; i++) {
		x[i] = ackermann(x, i);
	}
</PRE>
This removes any possibility of ambiguity
and reduces the chance of error with later enhancements/modifications.

<H2>Switch Statements</H2>

Switch statements should have the following form:
<PRE>
	switch (<I>selector</I>) {
	    case <I>first</I>:
	    case <I>the_second</I>:
	        <I>statements</I>;
	        break;

	    case <I>third</I>:
	        <I>statements</I>;
	        break;

	    case <I>dont_care_1</I>:
	    case <I>dont_care_2</I>:
	        break;

	    default:
	        fatal("Unexpected selector in '<I>procedure_name</I>'");
	}
</PRE>
Switch statements are the only departure from the "standard" indentation.
As will be mentioned in the <I>Indentation and Spacing</I> section,
the standard indentation is 8 spaces (one 8-space tab stop).
In switch statements,
the '<CODE>case</CODE>'s are indented 4 spaces from the '<CODE>switch</CODE>'
and the statements are indented 8 spaces (one tab) from the '<CODE>switch</CODE>'.
<P>

The last <CODE>case</CODE> of the statement should be followed by an explicit <CODE>break</CODE>,
even if it <I>is</I> the last choice in the statement.
This prevents potential oversight problems
when the switch statement is added to at a later time.
If the last choice in the switch statement is <CODE>default</CODE>,
it does not require a <CODE>break</CODE>.
<P>

In the case of enumerated types,
each element of the enumeration must have a "<CODE>case</CODE>"
in the switch statement.
In addition, a "<CODE>default</CODE>" must exist as the last choice
and must contain an indication that an error has occurred.
<P>

If the statements in a particular '<CODE>case</CODE>' do not end with a '<CODE>break</CODE>'
(thereby continuing control in the following '<CODE>case</CODE>'),
a bold comment should exist to indicate and explain the situation.
In addition,
it is recommended that a 'lint' style comment of the form
<CODE>/*FALLTHROUGH*/</CODE> be placed where a <CODE>break</CODE> might otherwise be.
To illustrate:
<PRE>
	/* Print numeric value. */
	switch (num->type) {
	    case signed_int:
	        putchar(num->negative ? "-" : "+");	/* Place the sign. */
	        /*FALLTHROUGH*/

	    case unsigned_int:
	        printf("%d", num->int_value);		/* Now print the value. */
	        break;

	    case floating_pt:
	        printf("%lf", num->fp_value);
	        break;

	    default:
	        warning("Unknown num->type encountered.");
	}
</PRE>


<H2>Function Standard</H2>

The proper form of a function declaration is as follows:
<PRE>
/*
 * <I>function_name</I>
 *
 *FUNCTION:
 * Interface specification.  Purpose of routine.  Expected usage.
 * Pertinent comments regarding return values.
 *
 *PARAMS:
 * Discussion of parameters.  Assumptions made about parameters, if any.
 * This section is necessary only if there is something more meaningful to be said
 * about the parameters that is not contained in their comments.
 *
 *LOGIC:
 * Internal operation and structure.  Algorithm description.
 *
 *ASSUMPTIONS:
 * Assumptions made that affect the correct functioning of the routine.
 *
 *NOTE:
 * Any special caveats, concerns, or special cautions.
 *
 *RETURNS:
 * Information regarding the possible return values.
 */

<I>return_type</I>
<I>function_name</I>(<I>param1</I>, <I>param2</I>)
<I>param_type</I> <I>param1</I>;		/* Purpose.  Expected values. */
<I>param_type</I> <I>param2</I>;		/* OUT:  (If modified.)  Purpose.  Expected values. */
{
	<I>type1</I> <I>variable1</I>,	/* Purpose of variable.  Description of use. */
	        <I>variable_the_second_of_this_type</I>;
				/*
				 * Purpose and description of this second variable.
				 * As much detail as necessary to make sense to others.
				 */
	<I>type2</I> <I>variable_3</I>;	/* Comment as above. */

	<I>CODE BODY</I>;

}/*** end <I>function_name</I>() ***/
</PRE>


While portions of the function's comment header may be omitted
if they have no meaningful content,
minimum necessities are the <CODE><I>function_name</I></CODE> and the <CODE>FUNCTION:</CODE> sections.
<P>

Each function parameter must be declared on a separate line.
Declarations of multiple parameters of the same type on the same line
is expressly forbidden, no matter how intimately related the parameters may be.
<P>

Although <B>C</B> assumes that a function
without a specified type returns an <CODE>int</CODE>,
this construct should never be used.
All functions should have either an explicit return type or <CODE>void</CODE>
(for "no return value").
If a function is specified as <CODE>void</CODE>,
it should never be used as an expression.
If a function is specified with an explicit return type,
it should never be used as a statement.
If the returned value is of no interest,
it is recommended that it be cast in the form:
<PRE>
	(void) f(x);
</PRE>
<BR>
or
<BR>
<PRE>
	dont_care = f(x);
</PRE>

<H2>Indentation and Spacing</H2>

With the specific exceptions mentioned earlier
in the section on <I>Switch Statements</I>,
the standard unit of indentation is an 8-space tab (or 8 spaces).
Use of tabs is encouraged,
but tab stops must be, <I>without exception</I>, 8 spaces.
(Due to the idiosyncrasies of text formatters,
tabs [or 8 spaces] may not be translated to paper accurately
for the examples in this document.
Assume indentation levels of 8 spaces if that appears to be the intent.)
<P>

Every <I>reasonable</I> effort should be made
to limit line lengths to 80 characters.
This improves the readability when looking at listings
or when viewing on standard (limited) alpha-numeric terminals.
While program understandability should not be compromised to meet this goal,
code which consistently breaks the 80 column barrier
may need to be justified before a higher court.
<P>

One of the primary purposes of spaces in a program is to enhance readability.
To this end, the use of horizontal and vertical spacing is encouraged.
As an aid to the uncertain reader, the following recommendations are provided:

<UL>
<LI>
At least three blank lines between routines.

<LI>
One space after a comma.

<LI>
Spaces around all assignment operators (<CODE>=</CODE>, <CODE>+=</CODE>, <CODE>-=</CODE>, etc.).

<LI>
One space on either side of a binary operator
(except for "<CODE>.</CODE>" and "<CODE>-></CODE>").

<LI>
No spaces between an identifier and "++" or "--".

<LI>
No space between a function name and its left paren.

<LI>
No extraneous spaces at the end of a line.
</ULy>

<H2>Comments</H2>

Comments are a vital and necessary aid to program understanding.
As this is one of our expressed goals, they are strongly encouraged.
It should be noted that this insistence on comments in the code
is not so much to help the original developer
(though they may prove useful in that regard),
as to support others who may become
involved with the code at some later date.
Whether next week, next month, or next year,
someone (potentially less brilliant) will need to understand the code
without the benefit of the developer's assistance.
This is the audience towards which comments should be directed.
<P>

Comments of the form:
<PRE>
	/*
	 * <Comment string>
	 */
</PRE>
are especially encouraged.
Whenever the closing delimiter (<CODE>*/</CODE>)
is not on the same line as the opener (<CODE>/*</CODE>),
it must be lined up with the opener (as above).
In addition, comments of the form:
<PRE>
	/*
	 * <Comment string> */
</PRE>
<BR>
or
<BR>
<PRE>
	/* <Comment string>
	 */
</PRE>
<BR>
or
<BR>
<PRE>
	/* <Comment string>
	 * <More comments>
	 */
</PRE>
are expressly forbidden.
<P>

Comments that refer to code that follows the comment
should be at the same indentation level as the code that follows.
Comments that directly refer to code just preceding the comments
should be indented one level from the indentation level of the preceding code.
To illustrate:

<PRE>
	/* Now get the next free index. */
	index = get_free_index(x_ptr);
		/* This returns either a free index or zero if there are none. */
</PRE>

In addition to the normal "good sense" commenting,
offensive code should be justified with profuse comments.
<P>

As aids to readability, comprehension, and organization,
comment "banners" acceptable by the code review committee are permitted
(though not required).
Some popular choices by those attached to this approach include:
<P>

<PRE>
/******************************************************************************/
/**************************** FUNCTION DECLARATIONS ***************************/
/******************************************************************************/

</PRE>
<BR>
or
<BR>
<PRE>
/**************************** VARIABLE DECLARATIONS ***************************/

</PRE>
<BR>
or
<BR>
<PRE>
/***********************/
/******  GLOBALS  ******/
/***********************/
</PRE>

A <I>^L</I> (Control-L) can be helpful in formatting output.
It causes a <I>page-feed</I>,
so subsequent text starts at the top of a new page.
If used, the <I>^L</I> should be on a line by itself.
At no time should it be considered acceptable to substitute
a <I>^L</I> for blank lines between functions.

<H2>Miscellaneous</H2>

As an aid to promoting good programming practice,
the use of the notorious "<CODE>goto</CODE>"s, "<CODE>setjmp()</CODE>"s,
and "<CODE>longjmp()</CODE>"s
are outlawed.
In order to employ such a construct,
it must be conclusively proven that to do otherwise
results in impossibly convoluted code.
<P>

Pointer arithmetic is potentially dangerous and should be used with care.
It goes without saying that <B>C</B> permits a wide latitude in pointer operations.
However, the fact that the language provides the means to hang oneself
does not necessarily mean that that is the thing to do.
Code will be far more readable and maintainable if such constructs are avoided.
While it is true that usage of the form:
<PRE>
	c = char_ptr++;
</PRE>
may be reasonable,
usage of the form:
<PRE>
	c = (char1_ptr - char2_ptr);
</PRE>
is a bad idea at best.
Rather than risk needless obfuscation,
it is recommended that all but the simplest pointer arithmetic
be avoided if at all possible.
Where its use is necessary,
the presence of explanatory comments is very strongly advocated.
<P>

Pointers should be compared to <CODE>NULL</CODE>
(from a header file such as <CODE>stdio.h</CODE>) rather than <CODE>0</CODE>.
<P>

Code that depends upon the order of evaluation of expressions is not acceptable.
Examples of such things are:
<PRE>
	a[i] = b[i++];			/* BAD! */
</PRE>
<BR>
and
<BR>
<PRE>
	x = f(a[i], i++);			/* MORE BAD! */
</PRE>
These come under the province of side effects and should be avoided
(as discussed in the section, <B>Expressions</B>).
<P>

In all cases,
code should be written to be as readable and understandable as possible
to someone with a moderate understanding of <B>C</B> and programming,
and a reasonable understanding of the program in question.
Where subtleties of <B>C</B> are necessary,
they should be commented clearly
so as to be readily understandable by any <B>C</B> programmer.
Where particularly involved or complex code is required,
comments should be copiously strewn about to promote better understanding.
At no time should code be written whose correct understanding
depends upon the detailed knowledge of the workings of a particular compiler.
<P>

Certain character strings have been reserved for use
under only certain conditions.
They serve as flags to alert us to circumstances
that may require special attention.
These reserved strings are expected to be used in comments
to indicate particular situations.
Their description and usage is as follows:

<DL>
<DT><B>TBD</B><DD> - This "flag" is used to indicate items
that require later definition.
It stands for <B>T</B>o <B>B</B>e <B>D</B>efined (or <B>D</B>etermined).
The ensuing comment should provide more particulars.

<DT><B>NYI</B><DD> - This "flag" is used to indicate items that have been defined
and are now awaiting implementation.
It stands for <B>N</B>ot <B>Y</B>et <B>I</B>mplemented.
The ensuing comment should provide more particulars.

<DT><B>MACHDEP</B><DD> - This "flag" is used to indicate the existence of an explicit
machine dependency in the code.
Again, the ensuing comment should provide more particulars.

<DT><B>BUG:</B><DD> - This "flag" is used to indicate the existence of a bug of some form.
It should be followed immediately in the comment (on the same line)
with one of the keywords <I>incomplete</I>, <I>untested</I>, or <I>wrong</I>,
to indicate its type along with a more descriptive comment if appropriate.
If none of the keywords is applicable,
some other descriptive word should be used
along with a more extensive comment.
</DL>

Machine dependent code should be avoided as much as possible.
Where absolutely necessary,
it should be localized in routines in a separate file if at all possible.
In all cases,
extensive comments are the order of the day.
<P>

The use of conditional compilation facilities is discouraged wherever possible.
When necessary,
it is recommended that it be localized in
header files and a separate "machine-dependent" code file.
<P>

Structure overlays
(casting one structure pointer type to a different structure pointer type)
should be avoided at all costs.
For those rare cases where they are absolutely necessary,
it is advised that they be localized
in a separate "machine-dependent" file with copious comments.
<P>

Avoid the use of unnecessary global variables.
<P>

The "<CODE>include</CODE>"ing of "<I>name</I>.c" files (code files)
is strongly discouraged.
<P>

Where disagreements arise,
the code review committee will have the final word
on the extent to which code is readable and understandable.
The request by a code review member for more (useful) comments
will be evidence that such comments are necessary.
Anyone responsible for coding in a manner at odds with these standards
under the assumption that <I>a)</I> no one will be reading their code,
or <I>b)</I> it will never go through code review (for whatever reasons),
or <I>c)</I> they just don't care,
will be suspended by their toes and shot at dawn.