Standard Indentation etc.

[Mark A Terribile]

> (plus various other things) I only feel strongly about a few
> indentation issues:
...
> Like everyone else said, having an indentation standard is more
> important than what the standard says. However, when you get into the
> topic of function and module headers, you will probably find more of a
> religious war, ...
> 
> These standards are crucial - you can't run code through a pretty-printer
> and get comments out. ... they should be flexible - decide on a list of
> things which can be described about ... (e.g. function arguments, return
> value, side effects, global dependencies, references, description.) Then
> only require those elements relevant to a particular function be put in
> that function's header.

There's really a lesson in all this, even as far as coding standards are
concerned:  allow the flexibility to do the thing right in several ways,
while making it harder to do things wrong.

Let's try some ideas:

	When writing standards for indentation and so forth, allow several
``styles'' but require that once a given file/module/whatever has been
begun in one, subsequent changes (short of a rewrite) must be done in that
same style.

	Decide what really HAS to be said and done.  Global data structures,
for example, often need six or seven times their own length in explanation.
Putting the function braces in the first column helps not only some emacs-
family editors, but vi as well.  Functions that are meant to be called from
outside their ``subsystem'' need man-page prologues.  Functions that are
functions only to keep another function from growing too bushy should probably
be described with their caller.  Functions that stand on their own, but that
are meant for use anywhere within a subsystem should at least have their
arguments and return values described.  Tricky algorithms should be described.
(But what constitutes ``tricky''?)  

	It makes sense to have headers in the function prologue so that
sections can be pulled out mechanically.  It makes less sense to require
that irrelevant sections be present, and less still to require that all
the sections be in a fixed order.

	The Procrustrean approach to programming style cannot guarantee
readable programs or intelligible, helpful documentation.  If the ``bed''
upon which the code is forced to fit is too uncomfortable, if its cost in
mental effort is too great, programmers will be distracted from the real
work: writing simple, expressive code and describing it clearly and
precisely.

	The latter point is too often neglected.  I've seen a real
unwillingness in code inspections to demand changes in imprecise or
unclear commentary.  ``Oh, give up, will you!  We all know what he MEANS.''
Well, if we all knew what he meant, there'd be no need for the comments
in the first place.  You *can't* create an objective, checklist criterion
for the style of prose in comments, but if the comments are needed at all
their quality is critical, and their quality depends upon the quality of
their style.

> That approach is close to what I find myself doing. It also avoids the
> trap mentioned in a previous discussion of coding standards - someone
> worked at a place where the mandatory function headers were so long
> that people combined functions to avoid writing headers.

Crap of this sort extracts a high price from programmers without buying
anything at all back.  When you put rules and procedures in place, you
should think of yourself as a shopper: you want to get the most payback
at the least cost.  The first thing you see on a shelf may not do that.
-- 

(This man's opinions are his own.)
>From mole-end				Mark Terribile