Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP
Path: utzoo!mnetor!uunet!seismo!ll-xn!husc6!yale!bunker!garys
From: garys@bunker.UUCP (Gary M. Samuelson)
Newsgroups: comp.lang.c
Subject: Re: Writing readable code
Message-ID: <2365@bunker.UUCP>
Date: Thu, 9-Jul-87 10:31:41 EDT
Article-I.D.: bunker.2365
Posted: Thu Jul  9 10:31:41 1987
Date-Received: Sun, 12-Jul-87 05:47:58 EDT
References: <598@nonvon.UUCP>
Reply-To: garys@bunker.UUCP (Gary M. Samuelson)
Organization: Bunker Ramo an Olivetti Company, Shelton CT
Lines: 137

In article <598@nonvon.UUCP> mc68020@nonvon.UUCP (mc68020) writes:

>   ... while all of this discussion about style,
>readability and portability is educational and even, for the most part, 
>enjoyable, I have seen not one mention of what I consider to be the single
>most important element of well written, portable code (in *ANY* language,
>not just C!).  That element is DOCUMENTATION.  COMMENTS.  

I heartily agree with the above and with most of what followed (deleted
to save space).

Since code will be read more times than written (hopefully, it will be
written only once), it should be written in such a way that it is easy
to read.  The headaches you save may be your own.  In particular, one
should resist the temptation to be clever just for the sake of cleverness.
Six months later, you won't remember why you yourself wrote that bizarre
piece of code, or why it works.  Even if you do, the peculiar circumstances
that made it work then don't apply anymore.

>    Frankly, I see two major classes of people foisting this crap off on the
>world:  those who are simply too lazy to do things correctly (probably far
>and away the largest group), and those whose arrogance causes them to 
>deliberate obfuscate.

Well, there is a third class.  Some of us are actually not permitted
to "do it right."

Out in the "real world," as they called it when I was still a student,
we have things called schedules and deadlines.  Documentation doesn't
get written because it takes time and might, the bosses say, delay the
introduction of our product past the time when it would make economic
sense to produce it.  Now I personally think this is shortsighted, and
penny-wise-but-pound-foolish, and that investing time in documentation
would save more than enough development time to justify it, even on the
short-to-moderate term, but I don't know how to prove it to the powers
that be.  Those one or two levels up say that they believe in the value
of documentation, but somewhere up the line the commitment is not there.
"Yes, documentation is important, but so-and-so customer is screaming
for such-and-such a feature, so we can't schedule time to write anything
but code."

I'm sure that there are published studies which show that writing
good documentation results in reduced development time, fewer bugs,
and ease of maintenance. Pointers, please?

But even if I present all the theory in the world, and point to my
own experience (MY software is always within a month of schedule),
the reply is always the same: "So-and-so customer is screaming...
we're going to lose a several million dollar contract..."  But at
some point improving the car is no longer worthwhile; it's time to
build a plane.  And while we're working on the plane, someone has
to start thinking about the rocketship.

People -- managers being no exception -- tend to believe what they
want to, and don't want to change (they would have to admit being
wrong in order to change).  Not even real life examples are always
persuasive.  In one case, I said to the boss three levels up, "Behold,
I did it my way, even the way I have been recommending as a better way,
and lo, the project was done on time, yea, even early."  (On time
around here is rare; early is unheard of.)  And this person actually
told me that if I had done it the Traditional way, it would have
take even less time.  An unassailable position, false though it be.

Well, managers have their problems, too.  Managers have to be able
to measure progress, and it's hard to measure the progress in a software
development effort, especially when software, per se, is not currently
being developed, but documentation is.  Lines of code per day is a rotten
metric, but what else is there?  LOC is zero during documentation, and
artificially high for inefficient programmers (if Goofus writes 100 lines
to perform a function that Gallant's 10 line function performs, it's Goofus
who appears more productive by the LOC metric).  Some measurement more like
features per fortnight is needed, but it's still going to be zero
during the documentation phase.

Then, when Goofus puts in lots of overtime to clean up what he should
have done right in the first place, he looks like the hero, and he gets
the bonus or the promotion.  Gallant, who works much more efficiently,
and has therefore completed his own tasks within a normal work week,
and still had time to help others, gets criticized for not putting out.

To change all this, you have to convince managers to start managing
differently.  So you say something like this: "Using our traditional
ways of development, this project is going to take two years (even though
the Old Guard who have been here forever have committed themselves to
a one year schedule).  Using the new state-of-the-art development
techniques, we (essentially, the new kids on the block) will complete
the project in 18 months.  This is six months more than the Old Guard
said it would take, but six months less than what it will really take
them, based on the fact that every project done by the Old Guard has
taken at least twice as long as the schedule said.  Since we are going
to spend two-thirds of our time planning and documenting, and only
one-third coding, if you use the metrics you are accustomed to using
(e.g., lines of code), there won't be any measurable progress for the first
12 months."

And the manager says, "I see.  You claim that our most senior,
most experienced engineers won't make their schedule.  You make
this claim with less than half the years of experience they have.
Further, you make this claim before the project even starts; before
they have run into any problems.  You further claim that you will
be able to meet your proposed schedule, even though the project hasn't
started, and even though you don't know what problems lie ahead of
you.  And you admit that for the first 12 months, I won't be able to
show *my* superiors any of the kind of progress that they have come
to expect, but after those 12 months are up, when the Old Guard says
they will be *done*, you will be ready to *start* coding.  And besides
all that, you expect me to measure your progress in a manner which you
yourself will prescribe."

"Well, yes, that about sums it up," you are forced to admit.

And the manager says, "Well, when you have a few more years of experience
then we will see what you can do when you are given a project to manage.
In the meantime, you'll have to work with the Old Guard and do things
their way."

And then you go off and learn how to do things the old way, and spend the
rest of your life holding one hand over your mouth (to keep from complaining
too much -- one has to have a good attitude, you know) and the other on your
stomach (to keep from retching every time you have to make your software
interface with spaghetti code that should have been re-written -- I won't
say re-designed, because it hasn't been designed the first time yet --
years ago).

>    Yes, I accuse many of the experts, particularly the older experts,
>of deliberately making their code difficult to read, and to understand.
>I believe their attitude is something like: "*I* had to suffer through
>poorly documented code, and no comments, so everyone else should too."

Well, I am not one of the older experts, but I have to confess to doing
what you say, but not for the reason you state.  I have written things
which were difficult to read not to confuse anyone, but because I was
trying to be "clever."  I have repented of such things, and try to
suppress that temptation now.  Ironically, some of these tricks I
gleaned from this network.

Gary Samuelson