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

[DHowell.ES at Xerox.ARPA]

It looks like it's time for me to bring another controversial message
into this mess.


Here is my basic opinion:  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.  

The harder a program is to change, the longer it takes.  And the time
wasted in trying to figure out how a program is working, (this could be
someone else's program, or it could be a program that you wrote months
or years ago) is probably more time that the time it would have taken to
make the program more readable.

---Concerning readability---

I have stated that i = i + 1 was more readable than i++.  The reason is
that i = i + 1 is a standard seen in many languages (only the assignment
operator has been changed to protect the computer scientists).  I have
even seen the machine language operator INC A defined as A <- A + 1.
Just as readable (or even more so) is "increment i", seen in some
languages in some form or another.  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.  "++" is
unique to C; I have never seen it in any other language.  The symbol
does not mean anything to anyone not versed in C, rather, it was
invented by the implementors of C to make things easier to type and
compile.  Now everyone says that anyone who knows anything about C knows
what "++" means, and yes that is true.  So if you must use your precious
"++" then go ahead, but make sure your comments explain what you're
doing.  The comment

  i++;  /* increment i */

has been called a non-comment, and it is for C programmers, but if any
non-C programmer needs to look at it (which you say never happens, but
I'm sure it happens more than you think) it is helpful.  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 */
 
  ptr++;  /* increment the pointer to the next element */
  
  while(ptr++->duck)  /* move pointer to the duck after the next NULL */
    ;

That last one is equivalent (in purpose) to

  while( ptr->duck != NULL )  /* move pointer to next NULL duck */
    ptr = ptr + 1;
  ptr = ptr + 1;              /* and increment to the one after it */

This form is more readable, but if efficiency is your thing, then the
first one is ok *AS LONG AS THE COMMENT IS THERE*.

And don't worry about efficiency until the program works!

The main problem I have with i++ and other such is that many programmers
do not comment their code enough, and i++, or even worse a?b:c (which
has been talked about a lot but its readability has not been discussed)
just makes the code harder to read.

To demonstrate, I am currently working on a program, written by someone
else, written in Mesa, a language similar to Pascal, but much more
modular.  The language is very readable as languages go.  The program
has very few comments.  (The majority of comments are the kind "END;
--of DisplayProc"; really helpful, eh?)  I think how much easier the
program would be to understand if it had comments.  But then I think how
much harder it would be to understand if it were written in C (without
comments).  But comments written in English explaining it all (not just
the top level but the details too) would help in any programming
language and I would be able to spend more time writing my own programs
than deciphering others' programs.  After all I thought we are hired as
programmers to write programs.

---Concerning professionalism---

If you are a programmer writing an accounting program, at least one of
two things has to happen:  The programmer must learn something about
accounting, or the accountant must learn something about programming.
This is true any time two professions must work together.   Each one can
make it easier for the other by doing their part make things more
understandable.  This is true professionalism, when one can work with
the other without too much difficulty.  Too many programmers seem to
believe that professionalism means just the opposite:  being able to be
understood only by one's own profession.  This mistaken belief leads us
into misunderstandings all over the place.  And misunderstanding is not
a good thing, especially when your trying to get something done.

Dan