Short Understandable Names

Abstract

Names of elements and attributes should short and understandable by authors and developers of processing software.

Problem

Names need to be given to each attribute and name.

Context

This pattern can be used in any document type. All documents have named elements and attributes.

Forces

Shorter names make the authoring of documents easier and reduces the overall length of documents. Names that are too short make the document difficult to understand.

Solution

Use names that are long enough to convey the meaning of the document to its intended audience, but are short enough to be typed easily. Similar naming length issues are seen in programming languages.

Examples

A element name such as TelephoneDescription is fairly long, PhoneDescription or PhoneDesc might be more appropriate choices.

Discussion

Use well known terms and abbreviations from the domain that the document deals with. These terms and abbreviations should be used consistently throughout the document. The audience of the document must be kept in mind, too much jargon can intimidate novices very quickly.

Context can be take into account to shorten names as well. In the following sample:

          

            <Telephone>
            <TelephoneModelName>X-259</TelephoneModelName>
            </Telephone>

The element name TelephoneModelName could easily be shortened to ModelName without loosing any understandability of the document.

Related Patterns

Known Uses

HTML uses many element names which are shortened beyond understandability, for example the b, i, dt, and ul elements are very cryptic to novice users. Element names such as font and img convey much more meaning, and are not long enough to cause problems.