Topic: descriptive naming

topics > Group: naming

denoting phrases and definite descriptions
file directory
encoded names
hierarchical naming
hypertext nodes made of names
name server or name directory
names as abbreviations for descriptions
naming conventions
software documentation
understanding systems
unique numeric names as surrogates
using a description as a name


The trend is towards long descriptive names for program documentation and maintenance. A well-chosen name or title reminds us of the purpose, or meaning, of the part being named. This makes it easier to understand a program.

A large number of short mnemonic names tend to make recognition difficult. (cbb 5/80)

Subtopic: descriptive names up

Quote: programming improved by indentation, comments, mnemonic names; but not by structured programming [»pariG_1980]
Quote: a well-chosen name reminds us of the purpose, or meaning, of the part being named [»hehnEC2_1984]
Quote: two levels needed for names: machine-oriented (a bit string) for storage, protection, etc; people-oriented (a mnemonic string) for reading [»watsRW_1981]
Quote: meaningful names important for debugging and when reading someone else's program [»goulJD9_1973]
Quote: use long names; if you can't read it out loud, it's a poor name [»kellD5_1990]
Quote: ML uses compound words to convey complex units of information, e.g., OvenIsHotEnough
Quote: Telesophy made of information units with a label that describes contents [»caplM12_1987]
Quote: an OS6 file index associates names (e.g., 'LinePrinter' and 'Text') with files; a file has two or more associations [»stoyJE3_1972]

Subtopic: suggestions for descriptive names up

Quote: use simple short names for types; e.g., Table, Error, State [»kellD5_1990]
Quote: use a verb for a procedure; if it applies to a type, include the type, e.g., StoreWord, DisplayError [»kellD5_1990]
Quote: use imperative verbs for procedures; nouns for attributes and functions; adjectives or questions for boolean queries [»meyeB9_1990]
Quote: for variables and functions, prefix their type name with an adjective; e.g., FirstState, NextState [»kellD5_1990]
Quote: boolean names should state a predicate, e.g., 'if PrinterIsReady' and '' [»kellD5_1990]
Quote: constants often define a limit; if so, use "Max" as a prefix [»kellD5_1990]

Subtopic: describe resource instead of naming it up

Quote: use intentional names in distributed environments that describe what is needed instead of where to find it [»adjiW12_1999]
Quote: the Intentional Naming System (INS) uses a hierarchy of attributes to locate services and route messages to the appropriate end-nodes [»adjiW12_1999]

Subtopic: symbols vs. words up

Quote: found that unusual symbols often convey meaning better than a reserved word; especially with children [»shocJF9_1979]

Subtopic: UI up

Quote: use copy-paste for descriptive names to avoid unnecessary typing

Subtopic: titles as descriptive names up

Quote: a name for a note is a mnemonic for its contents [»neuwC11_1987]
Quote: display menus of Atom entries using , <content>, and <summary> elements [<a href="thid-0698-8201-th-0946-2464">»</a>boswA10_2005] <tr><td><a href="thid-0400-6455-th-1520-0721">Quote</a>: the name of a relationship is a statement of a reason for an association [<a href="thid-0698-8201-th-0848-1472">»</a>kentW_1978] <tr><td><a href="thid-0400-6455-th-0465-3787">Quote</a>: in DocumentExaminer, nodes have a type ('variable') and a descriptive name [<a href="thid-0698-8201-th-1289-5155">»</a>walkJH11_1987] <tr><td><a href="thid-0400-6455-th-0028-7176">Quote</a>: a Telesophy label consists of a unique number, a description, and cataloging information [<a href="thid-0698-8201-th-0119-9363">»</a>caplM12_1987] <tr><td><a href="thid-0400-6455-th-1263-2865">Quote</a>: a Telesophy query produces summaries of each information unit (like titles) [<a href="thid-0698-8201-th-1270-0857">»</a>schaBR11_1987] <tr><td><a href="thid-0400-6455-th-1553-0732">Quote</a>: a DSEE task has a title which describes a high-level activity and a list of textual items defining necessary sub-tasks [<a href="thid-0698-8201-th-1480-9828">»</a>leblDB5_1984] <tr><td><a href="thid-0400-6455-th-0691-5860">Quote</a>: used ZOG for software management; statement titles are pseudo-code comments for begin-end blocks in Pascal [<a href="thid-0698-8201-th-0029-0644">»</a>akscRM5_1984] <tr><td><a href="thid-0400-6455-th-0356-5766">Quote</a>: each NoteCards card contains a title and arbitrary digital information <tr><td><a href="thid-0400-6455-th-0874-2925">Quote</a>: title cards by short phrases and use NoteCards browser to arrange them [<a href="thid-0698-8201-th-1384-8631">»</a>trigRH11_1987] <tr><td><a href="thid-0400-6455-th-1015-6592">Quote</a>: in Compendium, reference entries by their descriptive titles<br> [<a href="thid-0698-8201-th-0161-4408">»</a>glusRJ5_1989] </table></blockquote></th_quotes> <hr><p><a name=topics></a><b>Related Topics</b> <a href="#top"><img alt=up border=0 height=11 width=11 src="../images/up.gif"></a> <blockquote><th_xref><a href="thid-0513-0671-th-0356-3127">Topic</a>: denoting phrases and definite descriptions (21 items) <br><a href="thid-0513-0671-th-1086-8844">Topic</a>: file directory (55 items) <br><a href="thid-0513-0671-th-1116-8421">Topic</a>: encoded names (7 items) <br><a href="thid-0513-0671-th-1243-4586">Topic</a>: hierarchical naming (28 items) <br><a href="thid-0513-0671-th-1142-9377">Topic</a>: hypertext nodes made of names (13 items) <br><a href="thid-0513-0671-th-0360-3660">Topic</a>: name server or name directory (40 items) <br><a href="thid-0513-0671-th-0405-0134">Topic</a>: names as abbreviations for descriptions (35 items) <br><a href="thid-0513-0671-th-0954-2282">Topic</a>: naming conventions (8 items) <br><a href="thid-0513-0671-th-1619-3739">Topic</a>: software documentation (64 items) <br><a href="thid-0513-0671-th-0623-5921">Topic</a>: understanding systems (48 items) <br><a href="thid-0513-0671-th-1572-5927">Topic</a>: unique numeric names as surrogates (67 items) <br><a href="thid-0513-0671-th-0526-9423">Topic</a>: using a description as a name<br> (21 items) </th_xref> </blockquote> </td></tr></table> <hr><font size=-1> Updated barberCB 4/04<br> Copyright © 2002-2008 by C. Bradford Barber. All rights reserved.<br>Thesa is a trademark of C. Bradford Barber. </font> </body></html>