Style, readability, etc. (long, but IMPORTANT)

[J. Shapiro]

[Aren't you hungry...?]

Dan, I believe that you are saying something which is terribly
important, but I disagree very strongly with your examples, as I
believe that they contradict your point.

> Programs should be as readable as possible so
> that people who need to look at the code can understand it easily.  If a
> program is harder to read, it is harder to understand, and thus harder
> to change, debug, update, or whatever.

I agree completely, but starting immediately hereafter we disagree.

> But C comes up with i++ and ++i and
> confuses the issue by coming up with three different ways of
> incrementing a variable.  Seems to me only one is necessary.

These two operators perform significantly different functions which
enable the writing of tight code which is not (granted, to a C
programmer) obfuscated.  Indeed, many C programmers would find the
code which would be necessary to avoid these constructs in certain
places terribly indirect and confusing, which in some places it is.  I
too have used pascal and its brethren, and I believe that for some
tasks they are incredibly useful.  I prefer C for most applications
because of its flexibility of expression and its more sensible pointer handling.  Appropriately, my commenting
style varies in accordance with the language I am using.

> Now everyone says that anyone who knows anything about C knows
> what "++" means, and yes that is true.

If I understood you, your complaint here is that the arbitrary person
doesn't know about "++".  Your underlying implication here is that
programming languages should cater to the public's knowledge even at
cost of expressive flexibility.  To this I take exception.  A
programming language must strike a balance between expressive
flexibility to the programmer and legibility to the programmer and the
programmer's successors.  I am not convinced that my present employer,
who is a lawyer, should be able to read the code with no background
whatsoever, just as I cannot read or write contracts with full
understanding in the case of an adequately complex contract.  I am
firmly convinced that the code should be readable to another
programmer, and even to a fairly new C programmer, but if my employer
wants to read the code I feel that it is reasonable to insist that he
be willing to use the index of K&R, which is not long, or ask me about
whatever questions he may have.  The time and effort that this costs him
is substantially less than the time which lack of expressive flexibility
in the language would cost both of us.  Both of us are making a commitment.
I am making one to writing quality code within a time limit which
will be easily understood by anyone familiar with the language in question
with effort which is in proportion to the complexity of the task. My
employer is making a commitment not to hamper my efectiveness in performing
his task within the pre-established limits of budget, time, and human
tolerance.  He has every right to set INFORMED standards, and I
welcome his suggestions because they almost always give me better
insight into how to accomplish his task, but if his standards are
arbitrarily, unreasonably, and uninformedly applied, I will not work for
him, and neither will most other people I know.

I cannot think of any language which is easily readable to the general
uneducated public, including English.  Any demand which deprives me of
flexibility of necessity obfuscates my work, and makes that work
harder to accomplish. This is not in my or my employer's best interests.

> But even more
> helpful even for C programmers is a comment explaining why you are
> incrementing the variable, such as

> fish++;  /* we found another fish, so increment the fish counter */

I tend to prefer a block of comment describing the theory of operation
of the following section of code, and listing with the declaration of
each variable (other than i, j, and k, which I use exclusively for
loop control) its use.  This is more useful to a non computer type
than the individual comment, and is much more informative to the
experienced programmer than the disjoint comments.  It enables the
programmer to look at the code, know what it should do, and find the
broken case(s), which with disjointed comments is much more
difficult.  Comments need to be used selectively, so as to inform
without being condescending or extraneous.  Too much commenting is as
bad as too little, because it detracts from the attention that a
programmer or reader will apply to the comments in reading the code.
For example:
 
> ptr++;  /* increment the pointer to the next element */

This comment certainly does not tell the programmer of C anything, and
tells the novice nothing as well.  What the hell is a pointer,
anyway?  A pascal programmer can reasonably be expected to know
something about operators and computer languages, and to be smart
enough to look at whatever book is appropriate for reading a "foreign"
language.  Any programmer who is unwilling to do this is not being
responsible.
  
> while(ptr++->duck)  /* move pointer to the duck after the next NULL */
>   ;

This one is even more obscure than the last.  I am a C programmer, and
this tells me nothing - indeed it is dead wrong, as it simply will not
happen as the comment might lead me to believe.  This will leave me
with ptr pointing to the next available record whose element named
duck is 0.  It certainly has nothing to do with NULL or anything after
duck.  This is one of the major difficulties with such comments.
There is a tendency even among experienced programmers to read them
and believe them, and thereby not see an obvious difficulty.  On the
other hand, the comment does reveal to me that the author either
didn't have the foggiest notion about while termination (which in this
case seems unlikely) or was in another universe when he wrote the
comment.  This tells me that the program probably needs fundamental
rethinking, and is therefore only nominally useful.  Of course, if the
programming needs such rethinking, I most likely had already figured
that out on the basis of poor coding.

Your idea that things should be clear is correct, but I believe that
your opinions on what constitutes clarity could use further
examination.  I have never had anyone complain about the clarity of my
C code, and I have written many thousands of lines. I find that the
approach I teach leads my students to a much better understanding of problem
solving approach, which usually leads to superior results.  This is
becaus e the commenting style I advocate requires clear understanding
of the problem to effect properly. I certainly do not have the ideal
approach, nor do I believe that there is any such thing.  You might find
Kernighan and Plaugher's book _The Elements of Programming Style_ helpful,
though I have my disagreements with them as well.

Ultimately, I find that the clarity of the code produced correlates
directly with the programmer's understanding of the problem
constrained by the programmer's understanding of the language and the
programmer's overall competence.

I am sure you will receive other responses to your comments, and I
would welcome discussing this, but I suggest that further discussion
be conducted by mail.

Jonathan S. Shapiro
Haverford College
..!sjuvax!jss