Chapter 3: Readability - TOC - 3.1 SPELLING

3.1.4 Abbreviations

guideline

Do not use an abbreviation of a long word as an identifier where a shorter synonym exists.

Use a consistent abbreviation strategy.

Do not use ambiguous abbreviations.

To justify its use, an abbreviation must save many characters over the full word.

Use abbreviations that are well-accepted in the application domain.

Maintain a list of accepted abbreviations, and use only abbreviations on that list.

example

Use:

Time_Of_Receipt 

rather than:

Recd_Time or R_Time

But in an application that commonly deals with message formats that meet military standards, DOD_STD_MSG_FMT is an acceptable abbreviation for:

Department_Of_Defense_Standard_Message_Format.

rationale

Many abbreviations are ambiguous or unintelligible unless taken in context. As an example, Temp could indicate either temporary or temperature. For this reason, you should choose abbreviations carefully when you use them. The rationale in Guideline 8.1.2 provides a more thorough discussion of how context should influence the use of abbreviations.

Because very long variable names can obscure the structure of the program, especially in deeply nested (indented) control structures, it is a good idea to try to keep identifiers short and meaningful. Use short unabbreviated names whenever possible. If there is no short word that will serve as an identifier, then a well-known unambiguous abbreviation is the next best choice, especially if it comes from a list of standard abbreviations used throughout the project.

You can establish an abbreviated format for a fully qualified name using the renames clause. This capability is useful when a very long, fully qualified name would otherwise occur many times in a localized section of code (see Guideline 5.7.2).

A list of accepted abbreviations for a project provides a standard context for using each abbreviation.