Coding Standards (was Re: Indentation...)

[Dave Jones]

>From article <NELSON.88Dec13135433 at sun.soe.clarkson.edu>, by nelson at sun.soe.clarkson.edu (Russ Nelson):
...
> I got quite a few responses both by mail and by follow-ups to my
> query, in which I asked if there exist any standards for indentation.
> Several people pointed out that K&R use a consistent indentation in
> their books, and also that cb and indent will impose a consistent
> indentation.  Curiously, I didn't hear that people actually *use* K&R
> or cb formatting.
> 

I use a public-domain emacs "mode", just because it is convenient.
Occasionally I use "indent".

> The general advice that I got was to, when modifying existing code,
> stick to the existing style, and when creating new code, use a
> consistent style.
> 

Another alternative is to change the style of existing code by
running it through a pretty printer.  (If the author is still around
and views code as art, consider the political consequences before
you reformat it.)

> I also realize that the question that I meant to ask was larger than
> just indentation -- it also covers comment style, whitespace, brace
> positioning, etc.  So, to come to my rescue (?) is an article by Ken
> Arnold his C Advisor column in Unix Review Vol. 6 No. 12 on "Stylistic
> Stuff".
> 

I have that article in front of me.  It contains some good stuff.
But one of the examples in the article would not be acceptable to me as 
production code. I'm not calling the author to task.  The example
in question is only billed as illustrating comment usage, and I
have no disagreement on that subject. It's the names of the variables
and the manner in which they are declared that I would change.

For one thing, I virtually always give variables descriptive names
which can be spoken over the telephone.  I don't leave out vowels.
I spell everything out, except for standard abbreviations, such as
"init".

Only if the scope of a variable is extremely restricted and the purpose 
of the variable very obvious, will I use a name such as "i" or "j".
Even then, I am likely to feel a twinge of regret and change the "i" 
to "index" or something.  

I also am very meticulous about restricting the scope of variables.
Rather than having "reusable" global variables which function
differently in different parts of the program, I declare them in a
block which is active only so long as the variable is live:

   if (bye_required)
      { int byes_printed;
        for ( byes_printed = 0; byes_printed < 2; byes_printed++)
	   printf("bye");
      }
	        
I attempt to declare the variable as close as possible to the
first place were it takes on a meaningful value.

Notice that I don't always declare constant integers other
than 0 and 1 with #defines.  I #define a constant only if the
definition has abstraction value: for example, if the constant
appears in more than one place or might appear in more than one
place in a future version,  and is subject to change in future
versions. Documentation value is not enough.  If the constant is only
used in one place, then an inline comment can justify its existence,
and will not send the reader grepping through .h files to discover
what the value _really_ is.

I also try to use a very consistent style in data and procedure
definitions.  Structure-types are always capitalized. Routines that
deal pricipally with one kind of structure are named for the
structure, and the first paramenter is always a pointer to
the structure, and is always named "obj".  There is always
an initializer routine, a "new" routine, and when appropriate,
a "cleanup" routine which frees memory before a structure is discarded.

List*
List_init(obj)
  register List* obj;
{
  obj->first = (List_element*)0;
  obj->last = (List_element*)0;
  obj->count = 0;

  return obj;
}

List* 
List_new()
{
  return List_init(New(List));
}

Style can largely be viewed as being nice to prospective readers.
I restrict the scope of variables so that the reader need not "solve
theorems" to determine when values are live, and will not have
to search here and there in order to verify the effective scope
of the variable.   I avoid trival #defines in order to relieve
the reader of the necessity of grepping around in .h files.  If the
reader is likely to have a high-resolution monitor, I line up
the curly braces -- close brace under open brace -- to make
it easier to pair up the related ones.  If the reader is likely to
be using an old terminal, or the code is to be printed in book
format, I use the K&R style to save vertical space.