Path: utzoo!mnetor!uunet!husc6!cca!g-rh
From: g-rh@cca.CCA.COM (Richard Harter)
Newsgroups: comp.lang.misc
Subject: Re: Readable names
Message-ID: <25810@cca.CCA.COM>
Date: 21 Mar 88 07:19:09 GMT
References: <2857@enea.se> <25668@cca.CCA.COM> <2883@enea.se>
Reply-To: g-rh@CCA.CCA.COM.UUCP (Richard Harter)
Organization: Computer Corp. of America, Cambridge, MA
Lines: 63

In article <2883@enea.se> sommar@enea.UUCP(Erland Sommarskog) writes:
>Richard Harter (g-rh@CCA.CCA.COM.UUCP) writes:
>
>I must admit that I detest such naming conventions. Yes, if "na" is
>very frequent and appears everywhere, and is not accompanioned by "lp", 
>"oi" etc, well OK. But if I have to look up the definition each time I 
>see it, it's a big loss. This is exactly why dislike things like Unix
>and nroff with their short, seldom-mnemonic names. I find it very tire-
>some to have look up the same thing more than once. 

	Good point.  I can bear cp (rather than copy) precisely because
I use it frequently.  And rm is no worse than wondering if the command
is purge, flush, kill, or delete.  

>You write that this is your personal preference. I don't agree here.

	Now really, how can you say this?  If anyone is an expert on
my personal preferences, I am. :-)

>Most likely someone else will have to work with your code some day.
>I'm quite sure it will take him a longer time to understand your "na" 
>than NumberOfAccidents.

	I will have to disagree here.  As a caveat, I will immodestly
say that [some of] my code has been pointed out as exemplars of clear,
well written, well documented code.  More to the point, I have maintained
code written in both styles, written by both myself, and others, and I
find that documented code with concise variable names is easier to read
and maintain than code with large names, whether or not it is documented.

	Long names take longer to read and to write.  In particular, it
is harder to understand complicated statements.  Let me illustrate with
a ridiculous example, in no particular language:

	c = sqrt(a**2 + b**2);	/* Calculate hypotenuse of triangle a,b,c */

versus

hypotenuse_of_triangle_abc = sqrt(side_a_of_triangle_abc ** 2 +
	side_b_of_triangle_abc);

Notice the typo in the second version?  You did notice it, didn't you?
The length of the names didn't obscure the formula at all, or did they?

	I will grant that this is a contrived, and unfair example,
and that the names in my second example are not good ones.  Still, I
think the point is clear -- something that is easy to read (and write)
using short names, is actually less easy to read and write using long
names.

	Something that may be relevant is that I have been trained as
a mathematician.  I am much more comfortable with "let x be ..., y be
..., etc" and a body of work that uses x, y, etc, then with a style that
use wordy names instead of x, y, etc.  However I do insist on the definitions.
CODE THAT USES UNEXPLAINED AND UNDOCUMENTED SHORT NAMES IS HORRIBLE AND
UNMAINTAINABLE.  Another point is that the sort of code that I write and
prefer to maintain is written in small modules -- short names are much
more supportable if their scope is small.
-- 

In the fields of Hell where the grass grows high
Are the graves of dreams allowed to die.
	Richard Harter, SMDS  Inc.