NetNews Usenet Archive 1993 #1/NN_1993_1.iso/spool/comp/software/5233

Text File | 1993-01-06 | 6.5 KB | 173 lines

Newsgroups: comp.software-eng
Path: sparky!uunet!zaphod.mps.ohio-state.edu!saimiri.primate.wisc.edu!ames!george.arc.nasa.gov!lehman
From: [e-mail] (John Lehman -- GDP)
Subject: The tool is the (servant, master). Was: average identifier length.
Message-ID: <[e-mail]>
Summary: If its use is NOT optional, then it's probably a burden.
Sender: [e-mail]
Organization: NASA Ames Research Center, Moffett Field, CA
References: <[e-mail]> <[e-mail]> <[e-mail]>
Date: Wed, 6 Jan 1993 21:09:43 GMT
Lines: 160


Flint Pellet writes:
 >  A good number of years ago I worked in a
 > language where the convention "the rest of the world used" was that
 > a particular variable began with the two letters "nl" followed by digits.
 > (The n denoted integers, the letter l denoted "local".)  Unfortunately,
 > all the printed output went thru machines where the 1 and l used the
 > same character, which meant that an n11 (the eleventh global
 > integer) was indistinguishable from nl1: both printed as nll.  The
 > whole world was using typewriters like that, so I could not just
 > blithely say I needed a better printer.


That's a great example.  Even if 99% of the world's printers
use 2 characters for 1 and l, that's not much consolation
to the people who use the other 1%, who may be constrained
by time and money to use what they've got.

What is the lesson to be learned from the example?

Well, I'd say, the moral is that you can't be completely
sure that your work is good until the end user has finished
using it; and all you can do is try to anticipate _and_
_test_ as much as you can.  (In this case, print the code
on a printer and have a new person read it.)

Anyway, printer capability or not, it should be common sense
that 1 and l are going to look very much alike.  _If_ one has
the time to address such issues, then it might be good to
run a lint-like checker over the code, to look for 1's, l's,
0's, O's, and whatever else could lead to confusion.

(Of course one does want to be able to use ordinary words in a
program, like "local", which does have two l's in it.  No-one
would confuse that with 1oca1.)


To the person who pointed out, regarding \<i\> etc., that
saving keystrokes ala Taylor, by using the shortest possible
variable names, has little relevance to today's programmer:

Yes, of course you're right.  The more important thing is
how clearly understandable the code is.


"Don't hold your breath" for a widely adopted standard
on how to make code (or anything else) clearly understandable.
One way is to use simple sentences in code comments
(or in writing papers); and to write for a naive reader.
I also like to use short paragraphs!  I find them easier
to comprehend.  (I am guilty, if that's the word, of
using long sentences, though.)  Short lines of text
are good too.

Character recognition is a less significant issue.

For myself, to avoid character recognition problems,
I've toyed with the idea of using a character set without
0, O, 1, l, 2, Z, 5, S.  But, that would be too restrictive:
one also wants to be able to use the full alphabet and digit
set, and write code that's similar to natural language.


Re:  "the tool is the servant, not the master":

If I am getting a tutorial file off the net, and the
only copy I can find is a TeX file, then for me, TeX
is the master rather than the servant, at that point.
A lot of times I don't even HAVE a printer.  But if
I can get my hands on plain text, then the tools to
manipulate it are no burden:  I just use them naturally
to do whatever _I_ want to do.

(TeX is a tool for typesetting documents.  I'll write
more about "typesetting", below.  For that, please
remember the above example about getting a document
file off the net.)

A tool capability can become a tool burden, if its use
is NOT optional.

Enhanced capabilities of tools, which people are forced
to use, lead to no end of problems.  Some of the problems
may not surface until after a long time and far away.

If one wants to be safer, then there should be a
justification for every new feature used.  Don't use
a new capability which you don't need!  Spend a little
time deciding what you need.



My peeve is typesetting.  The following may seem like
railing.  It is related to the idea that the tool should
be the servant, not the master.


Typesetting is fine for getting a nice-looking document,
a persuasive document, even a more-clearly-readable
document in some cases.


_But_, for those rare :-) cases where one actually has
some important information :-!) which one wants to be
clearly _understood_,

              and

one wants the essential information to be _accessible_,
to a wide audience, or in a wide variety of circumstances
(including access by computers),

then plain text is better than a typeset document.


Even in restricted circumstances such as writing one
paper for one group of people, plain text is sufficient
to get the meaning across.

I do use typesetting programs.  They're fun, when I
have the time to play around with them.  I justify
the time spent by saying, people are used to typeset
documents and they'll pay more attention to my paper
if it is neatly typeset.

But that's all there is to it.

I apologize to typesetters and to people who write
typesetting programs.  It's just that your tools have
been misused by computer people.

The typesetting tools add very little to comprehension
of the material; and some accessibility of the material
is lost (one can now only access it through a printer,
and it is necessary to use certain software to decipher
it).

Typesetting is a trick to persuade people to read the
paper.

(Similarly, (to make the connection to the subject
matter of "comp.software-eng" more obvious) some software
enhancements are more show than go.)

The typesetting race is like the arms race and it is
like the Wall Street rat race.  It doesn't produce
much that is useful, but it spurs the economy by keeping
everyone running around in circles.

I would contend that this message which I have just
written, if it is not clearly understood, is not
the fault of its format or font, but rather the fault
of my sentences and paragraphs.  Also, if this message
is useful, then that usefulness is furthered by the
plainness of the format.  How many of you would have
read it if you could only obtain it in Postscript or
TeX or Microsoft Word format (or all three)?


[e-mail]