From: swisher@cs.utexas.edu (Janet M. Swisher)
Newsgroups: comp.programming
Subject: Re: Names
Date: 12 Apr 1992 00:53:54 -0500
Organization: CS Dept, University of Texas at Austin
NNTP-Posting-Host: boogie.cs.utexas.edu

In article <AJ3U.92Apr10183428@larch.cs.virginia.edu>
aj3u@larch.cs.virginia.edu (Asim Jalis) writes:
>Do people have ideas on how to name entities in programs
>(local/global variables, functions, types etc): some sort of
>general guidelines.  I have seen some articles on the Hungarian
>notation and have developed some conventions of my own also.
>However, I remain unsatisfied with this and would like to get
>more opinions.  Clearly, this is a very subjective issue.

A pretty-good article on this is: Keller, Daniel, "A Guide to Natural
Naming" in SIGPLAN Notices, 25:5 pp 95-102.  Keller also cites:
Ledgard, Henry, with John Tauer, _Professional Software, Vol. II,
Programming Practice_, Addison-Wesley, 1987.

Here is a summary of Keller's suggestions:

*Type Names
Should be shortest and simplest, and therefore must be chosen first,
especially before names of variables of the type.  Examples: Table,
Error, State, StateTable, FileName.

*Procedure Names
Should express the implied action of the procedure with a verb
("DoThis!") in the imperative form.  Combining the verb with the name
of the type operated on is often appropriate.  Examples:  StoreWord,
DisplayError, ShowPrinterStatus.

*Variable and Function Names
Combine a description (often an adjective) with the type name.  With
functions, use this to describe the returned value.  Examples:
FirstState, NextState, BigWindow, EndOfList.

*Constants
Treat pretty much like variables.  The prefix "Max" is often useful
for names of limits.  Examples: MaxLineLength, MaxLinesPerPage,
DefaultRepeatRate.

*Naming Order
1. Types
2. Procedure, Variables & Constants
3. Program & Modules (least important for readability)

*General Naming Hints

-- Names must be pronouncable 
"Rule of mouth": *If you can't read a name out loud, it's not a good
name.*  Do not truncate names unless you're using FORTRAN.  If you're
not a good typist, use a text editor to cut and paste.

-- Use capitalizing (or underscores) to mark the beginning of a new
word within a name.
This makes them more readable. 

-- Abbreviate with care.
Abbreviations are often ambiguous.  Example: does "Term" stand for
"Terminal" or "Terminate"?  Abbreviate a name only if it saves three
or more characters.  Examples:  "error" not "err", "next" not "nxt",
but "MaxLineLength" is OK for "MaximumLineLength".

-- Do not use numbers within a name.
They are easy to misread.  Try to find meaningful names.  Example:
PreviousPtr, CurrentPtr, and NextPtr, instead of p1, p2 and p3.  If
you really need to use numbers, try declaring an array of them
(Array[1..3] of Pointer to ...).

-- Boolean variables and function names should state a fact that can
be true or false.  This is easy if you use the verb "is".  Examples:
PrinterIsReady, QueueIsEmpty, Done, IOFailed.  This makes conditional
statements very readable.


I'm sure plenty of people will be able to come up with legitimate
reasons for violating any of these guidelines (no flames, please), but
it seems to me they make a pretty good starting point.