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: <25938@cca.CCA.COM> Date: 24 Mar 88 08:05:22 GMT References: <2857@enea.se> <25668@cca.CCA.COM> <2883@enea.se> <25810@cca.CCA.COM> <2902@enea.se> Reply-To: g-rh@CCA.CCA.COM.UUCP (Richard Harter) Organization: Computer Corp. of America, Cambridge, MA Lines: 77 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.