CSC/ECE 517 Summer 2008/wiki2 2 ao

Variable, Class, and Module Naming

When programming, choosing appropriate names for variables, classes, modules, etc. can often be taken too lightly. It's always important to choose descriptive names with straightforward meanings. Certain conventions should be followed to ensure code can be read, followed, and edited easily.

Naming conventions advantages

• to provide additional information (ie, metadata) about the use to which an identifier is put
• to help formalize expectations and promote consistency within a development team
• to enable the use of automated refactoring or search and replace tools with minimal potential for error
• to enhance clarity in cases of potential ambiguity
• to enhance the aesthetic and professional appearance of work product (for example, by disallowing overly long names, comical or "cute" names, or abbreviations)
• to help avoid "naming collisions" that might occur when the work product of different organizations is combined
• to provide meaningful data to be used in project handovers which require submission of program source code and all relevant documentation

Naming conventions disadvantages

• When a variable type is changed, you may have to go through and change all the instances of that variable within your code. The find-and-replace feature of many editors alleviates this issue a bit, but it may still be tedious.
• If your language changes, i.e. is updated, code may need to be changed so the naming convention still fits.
• Naming conventions may defeat the purpose of encapsulation. The "black box" aspect is eliminated when the programmer needs to know what specific type is being returned.

Common conventions

• Packages should have prefixes always written in all-lowercase ASCII letters and they should be one of the top-level domain names, currently com, edu, gov, mil, net, org, or one of the English two-letter codes identifying countries as specified in ISO Standard 3166, 1981. Examples: com.sun.eng, com.apple.quicktime.v2, and edu.cmu.cs.bovik.cheese.
• Class names should be nouns, in mixed case with the first letter of each word capitalized. They should be simple and descriptive, and whole words should be used (avoid acronyms and abbreviations). Examples: class Roster;, class ImageSprite;.
• Interface names should be capitalized like class names. Examples: interface RosterDelegate;, interface Storing;.
• Lowercase letters should be used for variable and method names. A name consisting of several words should be concatenated into one word (take out the spaces). The first word should be all lowercase, and each subsequent word (the internal words) should have its first letter capitalized. Methods should be verbs. Examples: run();, runFast();, and getBackground();
• Variable names should be short yet meaningful. The choice of a variable name should be mnemonic- that is, designed to indicate to the casual observer the intent of its use. One-character variable names should be avoided except for temporary "throwaway" variables. Common names for temporary variables are i, j, k, m, and n for integers; c, d, and e for characters. Variable names should not start with underscore ("_") or dollar sign ("$") characters, even though both are allowed. Examples: int i;, char c;, and float myWidth;.
• The names of variables declared class constants and of ANSI constants should be all uppercase with words separated by underscores ("_"). Examples: static final int MIN_WIDTH = 4;, static final int MAX_WIDTH = 999;, and static final int GET_THE_CPU = 1;.

Hungarian notation

One of the most popular naming conventions is Hungarian notation, which encodes either the purpose ("Apps Hungarian") or the type ("Systems Hungarian") of a variable in its name. Some examples of "Apps Hungarian" are:

• rwPosition: variable represents a row ("rw")
• usName: variable represents an unsafe string ("us"), which needs to be "sanitized" before it is used
• strName: Variable represents a string ("str") containing the name, but does not specify how that string is implemented

Some examples of "Apps Hungarian" are as follows:

• lAccountNum: variable is a long integer ("l")
• arru8NumberList: variable is an array of unsigned 8-bit integers ("arru8")
• szName: variable is a zero-terminated string ("sz")

Final conclusions

The advantages of using naming conventions outweigh the disadvantages. Readability is the biggest derived benefit, and its importance cannot be overstated. Variable types, as well as their purpose (for classes and modules too) can be determined at a quick glance. Readers unfamiliar with the code can derive meaning and purpose quicker, without having to study large portions of the code and refer to various places within. The following tips should be used when choosing names for variables, classes, modules, etc.:

• Prefix the variable names with their scope and their data types
• Use meaningful variable names
• Be wary of long names
• Use your conventions consistently

References

• Liang, Y. Daniel. Introduction to Java Programming: Comprehensive. Pearson Prentice Hall, 2008.

External Links

• http://frontier.userland.com/tutorial/variableNaming
• http://www.programmers-corner.com/article/18
• http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html
• http://www.cprogramming.com/tutorial/style_naming_conventions.html
• http://www.uwe-sauerland.de/richtlinien/naming.html
• http://www.kamath.com/columns/squareone/so001_whatname1.asp
• http://java.sun.com/docs/books/tutorial/java/nutsandbolts/variables.html
• http://en.wikipedia.org/wiki/Identifier_naming_convention
• http://www.erlang.se/doc/programming_rules.shtml