🚀 go-pugleaf

In article <2902@enea.se> sommar@enea.UUCP(Erland Sommarskog) writes:
>Richard Harter (g-rh@CCA.CCA.COM.UUCP) writes:
>>	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.  

>Well, I haven't seen it, so I can't judge. You have to post some of that
>wonderful code. :-)

	Not on your life!  Praising your own accomplishments works much
better if you don't embarrass yourself by making them public.  :-)
>I beginning to feel that I am repeating myself. But it takes longer to read
>"na" than "NumberOfAccidents", unless you managed to burn a hard link
>that gives an immediate understanding of "na". Else you have to waste time
>to look it up or recall what it means. Same may be valid for typing: "What
>abbreviation did I use?"

	Oh, I see your point alright.  I find NumberOfAccidents hard
to read and unpleasant, whereas Number_of_Accidents is more pleasing to
mine eye.  In either case it is quite clear what the variable is, whereas
na is simply cryptic.  Or is it?  Suppose we have several types of accidents,
and partial sums, and so on.  Even so, the short names remain cryptic.

	However the issue is not, as I see it, one of reading variables,
it is one of reading lines of code and blocks of code.  Suppose, for example,
that you use names 15-20 characters in length and that the statement has half
a dozen names in it  -- you now have statements ~100 characters in length.
Moreover, your code, depending on the task, may have big blocks of this
long winded code.  Another consideration is that variables typically do
not occur as isolated instances; they tend to appear in closely joined
statements.  If you see na once and Number_of_Accidents once, the former
is cryptic and the latter is self documenting.  If you see them ten times
it becomes worth your while to understand what na means, and the self
documenting feature of Number_of_Accidents is redundant.

	However, if one uses short names, documentation becomes very
important.  As an example, I recently came across a listing of a scratch
test program I wrote about 15 years ago.  This program used one and two
letter names, and had no comments whatsoever.  [Not to sniff and hold your
nose up; it was a one time test program of about 200 lines; it was written
with the intent of being used once and being thrown away; the saving of
the listing was pure chance.]  Now, when I wrote it, I knew exactly what
it did.  From the listing it is nearly impossible to understand what it
does, what the algorithm being tested was (or how it worked), and what the
output represented.

>>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.

>Yes, short names are more acceptable in a small scope. But even if your
>modules are small, you have a lot of global names: procedures, types,
>constants, enumeration values and field elements in records. You use
>your short names for these too?

Depends -- procedure names are usually 6-8 characters to avoid portability
problems in the software I am working with now.  Also, cross reference
listings are more readable if all names are about the same length.  The same
is true of global variables (All code currently is C).  These names are
all compressed names with standardized abbreviations, e.g. cmpdir is
'compress directory', assion is 'assign insertion order number', 'dspbib'
is 'display bibliography'.  Names global to a file are short if they are
common, longer if they are not.  Field elements are almost always short.
Flags and enumeration values are ususally full words.  One letter names
almost always have a standard meaning, e.g. i is a loop index, n is the
number of values of something.  Types are treated much the same as globals.
Also relevant is the fact that I annotate every line, ala assembly language
code, unless it is too long to fit a comment field in.  Normal format is
a code field of about 40 chars wide and a comment field of about 35 chars
wide with all comments aligned.  As you may imagine, short names are more
attractive with these constraints :-).    I have been using this style for
about 6 years now, having used others (including long names).
-- 

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