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

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

In variable declarations,
there should be only one identifier on a line.
Multiple identifiers and/or multiple identifier assignments on a line
are not acceptable unless they are intimately related,
and even then they are not encouraged.
<P>

Numerical constants should not be coded directly.
Instead the "<CODE>#define</CODE>" facility should be used.
Constants declared explicitly "<CODE>long</CODE>"
should use a capital "<CODE>L</CODE>".
It is too easy to confuse letters and digits if this rule is not followed
(i.e. <CODE>2l</CODE> [2-el] looks too much like <CODE>21</CODE> [twenty-one]).
<P>

For external arrays, repeat the array bounds declarations.
Since (given the preceding paragraph)
any fixed limit should be "<CODE>#define</CODE>"-ed,
there should be no problem with maintainability.
<P>

Never default "<CODE>int</CODE>" declarations, whether functions or parameters.
<P>

The generous use of the keyword "<CODE>static</CODE>"
on global functions and variables is encouraged
to restrict their visibility outside the file.
Global accessiblity of variables is discouraged without good reasons.
Conversely,
the use of local "<CODE>extern</CODE>" declarations
within functions is actively discouraged without strong justification.
<P>

In general, it is a poor idea to employ local declarations
that override declarations at higher levels.
<P>

Particularly in the case of <CODE>struct</CODE>s,
types and instances of types should not combined in the same declaration.
To illustrate, the following is <B>not</B> acceptable.

<PRE>
	struct windmill {
		int	num_sails;
		int	usage;
		int	style;
	} don_quixote;				/* WRONG */


</PRE>
<BR>
Rather, it should be:
<BR>
<PRE>
	struct windmill {
		int	num_sails;
		int	usage;
		int	style;
	};

	struct windmill	don_quixote;	/* RIGHT */
</PRE>

<H2>Expressions</H2>

It has been said that there is little one can do about the problems
caused by side effects in parameters
except to avoid side effects in expressions.
These are commendable words and should be adhered to rigorously.
Remember that the "<CODE>++</CODE>" and "<CODE>--</CODE>" operators are also
assignment operators and thus <I>do</I> produce side effects.
<P>

Conditional expressions (<CODE>a ? b : c</CODE>),
are not intuitive,
can be confusing (particularly nested conditional expressions),
and should be avoided.
Where appropriate, the approved form is:
<PRE>
	(<I>condition</I> ? <I>true_return_val</I> : <I>false_return_val</I>)
</PRE>
where the parentheses and the spaces around the "<CODE>?</CODE>"
and "<CODE>:</CODE>" are mandatory.
In addition,
if any portion of the expression is other than a simple expression,
parentheses around the offending section are encouraged.
<P>

Expressions that span multiple lines should be split before an operator,
preferably at the lowest-precedence operator near the break.
<P>

When using negation (!) in conditional expressions,
it is recommended that the expression to be operated upon
be enclosed in parentheses
to improve readability and remove any ambiguities that might arise.
<P>

The use of left-shift and right-shift operators
should be reserved for bit operations.
Their use for multiplication, division,
and exponentiation is strongly discouraged.
(Besides, most intelligent compilers will recognize the arithmetic cases
and produce <I>shift</I> code for them, anyway.)
<P>

<H2>Assignment Statements and Initializations</H2>

There is a time and place for embedded assignment statements, but rarely.
In general they should be avoided.
The primary acceptable instance is in conditional statements
to check for special conditions.
The two best examples are:
<PRE>
	if ((obj_ptr = malloc(elem_num, elem_size) == NULL) {
		<I><Handle memory exhaustion condition></I>
	}
</PRE>
<BR>
and:
<BR>
<PRE>
	while ((c = getchar()) != EOF) {
		<I><Process character></I>
	}
</PRE>
Remember, an embedded assignment statement is a form of side effect
(and that "<CODE>x++</CODE>" and "<CODE>x--</CODE>"
are also assignment statements.)
<P>

Unless a local variable is going to be used very shortly after it is declared,
it is recommended its initialization be performed at its point of first use
rather than where it is declared.
Global variables should be initialized where declared.
If this is not convenient (e.g. large arrays),
they should be initialized in a dedicated initialization routine.
In the case of dynamic initialization of structure variables,
initialize the fields in the order in which they are defined.
To illustrate:
<PRE>
	typedef struct {
		int	maker;
		int	model;
		int	year;
		int	color;
	} car;


	car	my_car;

	my_car.maker = PORSCHE;
	my_car.model = most_expensive;
	my_car.year  = this_year;
	my_car.color = RED;
</PRE>

Since we live in an imperfect world,
do not assume that uninitialized variables
will be set to zero by the compiler.
While this might be the case,
resist the temptation to succumb to this assumption.
If the initial value of a variable makes a difference,
initialize it explicitly.
<P>

Along these lines,
remember that that memory allocated by <CODE>malloc()</CODE>
will not be zeroed.
If it is important to have dynamically allocated memory zeroed
(usually a good idea), <CODE>calloc()</CODE> should be used.
(With respect to dynamic memory allocations,
the reader is referred to the "safer" versions of these routines
discussed in the <B>P6 System Header File</B> appendix.)
<P>

<H2>Simple Statements</H2>

For the purpose of the ensuing discussions,
we wish to define what we mean by a "simple" statement.
A simple statement is one of three possibilities:
<PRE>
</PRE>
<BR>
It is either a simple assignment:
<BR>
<PRE>
		a = x[i];
</PRE>
<BR>
	or
<BR>
<PRE>
		a = f(x);
</PRE>
<BR>
a simple increment:
<BR>
<PRE>
		i++;
</PRE>
<BR>
	or
<BR>
<PRE>
		m = m + n;
</PRE>
<BR>
or a function call:
<BR>
<PRE>
		f(a, b, c);

</PRE>
<BR>
It is doubtful that:
<BR>
<PRE>
		*z[t] = f(x[f1(i)], f2(y[j] + n), k * r(s));
</PRE>
<BR>
could be considered a simple statement.
<BR>
<PRE>
</PRE>

<H2>Conditional Statements</H2>

The form of conditional statements is as follows:
<PRE>
	if (<I>condition</I>)
		<I>simple_then_statement</I>;
</PRE>
<BR>
or (preferable)
<BR>
<PRE>
	if (<I>condition</I>) {
		<I>then_statements</I>;
	}
</PRE>
<BR>
With an <CODE> else </CODE> part:
	if (<I>condition</I>)
		<I>simple_then_statement</I>;
	else
		<I>simple_else_statement</I>;
</PRE>
<BR>
or
<BR>
<PRE>
	if (<I>condition</I>) {
		<I>then_statement(s)</I>;
	} else {
		<I>else_statement(s)</I>;
	}


</PRE>
<BR>
For complex conditions:
<BR>
<PRE>
	if (    <I>condition_1</I>
	    && (<I>condition_2</I> | | <I>condition_3</I>)
	    &&  <I>condition_4</I>) {
		<I>then_statements</I>;
	} else {
		<I>else_statements</I>;
	}


</PRE>
<BR>
For nested if's, the proper form is:
<BR>
<PRE>
	if (<I>condition1</I>) {
		<I>statements</I>;
	} else if (<I>condition2</I>) {
		<I>statements</I>;
	} else if (<I>condition3</I>) {
		<I>statements</I>;
	} else {
		<I>statements</I>;
	}


</PRE>
<BR>
For nested control structures (including nested "if" statements), compound statements are required.
To illustrate, the following is <B><STRONG>not</STRONG></B> allowed:
<BR>
<PRE>
	if (<I>condition1</I>)
		while (<I>condition2</I>) {
			<I>statements</I>;
		}
	else
		<I>else_statement</I>;		/* WRONG */


</PRE>
<BR>
Rather, the approved form is:
<BR>
<PRE>
	if (<I>condition1</I>) {
		while (<I>condition2</I>) {
			<I>statements</I>;
		}
	} else {
		<I>else_statement</I>;		/* RIGHT */
	}


</PRE>
<BR>
The use of compound statements is recommended to avoid ambiguity.  The following is <B><STRONG>not</STRONG></B> acceptable:
<BR>
<PRE>
	if (<I>condition1</I>)
		if (<I>condition2</I>)
			<I>simple_then_statement</I>;	/* WRONG */
	else
		<I>simple_else_statement</I>;


</PRE>
<BR>
It is better to use either
<BR>
<PRE>
	if (<I>condition1</I>) {
		if (<I>condition2</I>)
			<I>simple_then_statement</I>;
	} else {
		<I>simple_else_statement</I>;
	}
</PRE>
<BR>
or<CODE>
	if (<I>condition1</I>) {
		if (<I>condition2</I>) {
			<I>simple_then_statement</I>;
		} else {
			<I>simple_else_statement</I>;
		}
	}
</PRE>
(Depending upon what was intended.)
<P>

The only time brackets are <B>not</CODE> required on <B>all</B> parts
of a conditional statement
is when all parts of the conditional statement are simple statements
(as defined above in the <B>Simple Statements</B> section).
In other words,
if <B>any</B> part of a conditional statement is a compound statement
(for whatever reason),
then <B>all</B> parts must be compound.
<P>

In general, the use of compound statements {}
is encouraged as an aid to readability and maintainability.
<P>

<H2>Iterative Statements</H2>

Iterative statements should be of the form:
<PRE>
	while (<I>condition</I>) {
		<I>statements</I>;
	}
</PRE>
<BR>
or
<BR>
<PRE>
	do {
		<I>statements</I>;
	} while (<I>condition</I>);
</PRE>
<BR>
or
<BR>
<PRE>
	for (i = <I>initial</I>; <I>condition</I>; <I>next</I>) {
		<I>statements</I>;
	}


</PRE>
<BR>
For infinite loops, the recommended form is:
<BR>
<PRE>
	while (TRUE) {		/* (If TRUE has been defined nonzero.) */
		<I>statements</I>;
	}
</PRE>
<BR>
or
<BR>
<PRE>
	while (1) {
		<I>statements</I>;
	}
</PRE>

If there is only a single, simple statement to be executed,
the brackets {} are not required but <I>are</I> encouraged.
In any event,
the statement to be executed must be on a line of its own.
<P>

If an iterative statement has a null (empty) body,
it should use an empty compound statement containing a comment
verifying its emptiness.
<PRE>
	/* Find where strings differ. */
	while (*str1++ == *str2++) {
		/* VOID */
	}
</PRE>

The use of the "<CODE>continue</CODE>" statement is not encouraged.
When used, it should be commented explicitly and,
if possible, used early in the loop body.
In addition,
appropriate comments should added to make it easy to determine
its target.
<P>

<H2>Compound (Bracketed) Statements</H2>

As mentioned earlier,
there is no requirement to use brackets {} in iterative statements
if there is only a single, "simple" statement to be executed.
The same was said to be true for conditional statements,
with the added proviso that if <I>any</I> statement in the conditional statement
was compound,
then <I>all</I> statements were required to be compound.
<P>

In these cases,
although the brackets are not required
they are strongly recommended as an aid to maintainability.
To illustrate this, consider the following calculation of Ackermann function values:

<PRE>
	x[0] = 1;
	x[1] = 1;
	for (i = 2 ; i <= LIMIT ; i++)
		x[i] = ackermann(x, i);
</PRE>

Should we later decide to sum the values as we go along, we might unwittingly add:
<PRE>