Naming & Coding Conventions

by Serguei A. Mokhov
Some parts borrowed from Merck Frosst's R.I.S. Department Coding Conventions by Jean Marois.

$Revision: 1.2 $

$Date: 2007/08/03 02:44:04 $

Table of Contents

Brief Intro

This section describes our proposed common naming and coding conventions, which all of us will follow in order to achieve consistency and uniform style in our projects.
[TOP]

Hungarian Notation

This technique makes programming easier, because it gives you a simple mental machine for naming the things in your code. A guy, Charles Simonyi, invented that technique that solves an old and tiresome programming problem: "What am I going to name this variable?" He realized that there are two important aspects to think about when writing code: what a thing is, and what it means. To write good programs in strongly-typed languages, you really need to keep both of these things in mind. The "traditional" naming technique uses names that emphasize what a thing means, requiring you to memorize its declaration to remember what that thing is. While good in its intention of making code "readable", this traditional kind of naming often results in two things:

  1. code that is understandable only by someone who is very determined, and
  2. bugs.

Hungarian names have two parts. The prefix contains type information specifying what this thing is, while the suffix contains descriptive information specifying what it means. The prefix is composed of standard elements that are the same for any program you write in a given language. The suffix is composed of English words that tend to be application-specific.

The prefix elements used here are not the only ones possible, but they have some particularly nice properties. First, they are highly mnemonic, so it's easy to remember what they mean. Second, they all consist of a single or a few letters. This becomes important when multiple prefix elements are composed in the same name. A prefix can show a lot of information in a few characters, without possibility of confusion about how those characters are associated.
[TOP]

Simplified Hungarian Notation for the Team

Common Naming Rules

This proposed naming scheme is supposed to be used by everyone programming in Java to maintain consistency among the code base for the projects where the Java programming language is used.

Class Names

  1. All names of all classes start with the capital letter;
  2. If the class name is a multiword name, every single word must be capitalized;
Examples:

Method Names

  1. First letter of every user-defined function is in lower case;
  2. If the function's name has multiple words every other word should be capitalized;
  3. For getters and setters (class methods that set or return data members of the class) should have get and set prefixes, and after property name starting with capital letter;
  4. Name of the function has to have a meaning, obviously.
Examples:

Variable Names

  1. Each variable starts with a special prefix indicating variable's scope.

    There four special prefixes in the "classical" form. First, I will present the classical form, and then will adapt it for Java.
    Prefix Description
    m_ The prefix denotes a member variable of a class.
    p_ This prefix shows that the variable is a parameter in the function's signature.
    l_ This prefix is used for the local scope variables (e.g. inside a function)
    g_ This prefix describes variables belonging to the global scope.


    Modifications for Java:
    • Since in Java we don't really have the global scope, we can drop the "g_" prefix.
    • Additionally, to distinguish the member and local variables, it is proposed to use the following: drop "l_" from the local variables and assume a variable to be local if it has no prefix.
    • For member variables we will explicitly prefix them with "this.".
    • The last simplification would be to drop the underscore from "p_", but a variable name still should have a letter p to indicate that this variable is a parameter variable. E.g. piID in getProductInfo(int piID).
  2. The next part of the variable name is its type. This is especially useful for the languages where the data type doesn't really exists like PHP, PERL, and JavaScript, and it might not be clear from the variable's declaration what type of value it has. In addition, specifying the type improves readability of the code and reduces number of bugs related to misinterpretation of the variable's value type.

    For the primitive data types (like integer, floating point, character, Boolean, etc.) we'll use one letter (i, f, c, b respectively). The more complete list provided below:
    Letter Type
    i int
    l long
    f float; floating point, single precision
    d double; floating point with double precision
    c char
    b boolean
    t byte

    For more complex data structures, such as arrays, character strings and different types of objects we'll use the following:
    • Array data type is denoted by the letter "a" followed by the type of elements of this array.
    • Arbitrary objects created using user-generated classes are denoted by the letter "o" followed by full or partial (but clearly identifying) class name.
    • For the String data type we'll use three-letter notation str.

    After all type identifications some (logical) wordings may follow to distinguish variables of the same type in the same scope.

    Examples:

    Variable Name Meaning
    iIndex This is a local variable of an int type, named Index.
    oGun This is a local variable of type of an object of class Gun.
    this.acMyCharArray This is an array of characters named MyCharArray, which is a member variable.
    poGunRevolver This is a parameter variable passed to a function of type of object Gun, named Revolver
    (void myFunc(Gun poGunRevolver) {})
    strError This is a character string variable named Error.

Method Names vs. Variable Names

Variable names are not at all similar to the method names for the following reasons: the ALWAYS have different prefixes -- the variables have the scope and the type, where 99% methods begin with an English word and have no typing information in them. Additionally, method calls always have parentheses "(" and ")", so no confusion there can possibly be.

Constants

Constants may follow the same rules as the variables as far as prefixes concerned (optionally), and usually are CAPITALIZED. Every other word in the case of a multiword constant (and with capitalization) must be separated with underscores "_".

E.g.: public static final int DEFAULT_NUMBER_OF_WORKERS = 13;

Other Coding Conventions

Putting all together:

/**
 * Class Gun that fires.
 * Provides ability to set index and fire.
 * @author Gun Shop
 * @version $Revision: 1.2 $
 * @since 1.2.3
 */
class Gun
{
	/*
	 * -----------------
	 * Getters / Setters
	 * -----------------
	 */

	/**
	 * Last Error Occurred.
	 */
	private String strError;

	/**
	 * Serial Index of the Weapon (if such exists :)).
	 */
	private int iIndex;


	/*
	 * ---------------
	 * Object Lifetime
	 * ---------------
	 */

	/**
	 * Constructor.
	 * @param piIndex Serial number of the gun
	 */
	public Gun(final int piIndex)
	{
		setIndex(piIndex);
	}


	/*
	 * -----------------
	 * Getters / Setters
	 * -----------------
	 */

	/**
	 * Retrieves the serial index of the weapon.
	 * @return Gun's serial index
	 */
	public final int getIndex()
	{
		return this.iIndex;
	}

	/**
	 * Sets the serial index of the weapon.
	 * @param piIndex Gun's serial index
	 */
	public final void setIndex(final int piIndex)
	{
		this.iIndex = piIndex;
	}

	/**
	 * Retrieves the error message of the last error occurred.
	 * @return Last error message string
	 */
	public final String getError()
	{
		return this.strError;
	}


	/*
	 * ----------------
	 * Public Interface
	 * ----------------
	 */

	/**
	 * Fires the gun.
	 */
	public void fire()
	{
	}
}

/**
 * Main startup module.
 */
public class Main
{
	/**
	 * Important array of integers shared among all class
	 * instances.
	 */
	private static int[] saiMyIntArray = {1, 2, 3, 4, 5, 6, 7};

	/**
	 * argv here left as-is for historical reasons, but may
	 * be changed to pastrCommandLineArgs or whatever plausible
	 * replacement is.
	 * @param argv command line arguments vector
	 */
	public static void main(String[] argv)
	{
		new Main().use(new Gun());
	}

	public void use(Gun poGun)
	{
		//...
		poGun.fire();
		//...
	}

	public void errorHandler(int piErrorID)
	{
		//...
	}
}
	

[TOP]

Static (Class) Variables and Interfaces

  1. Static variables. Static (a.k.a class) variables cannot be referred to as members even though they are defined within the class' scope, so no "this." prefix can be used. However, if we omit the prefix, it will look like as if we are using local variables inside our methods. Therefore, we will use the "s" prefix for statics as we do use "p" for parameter variables. Examples: private static sstrFormName = "";, public static int siNextTID = 1;
  2. Interface Names. There's a common convention to place "I" before an Interface, like in ICommunicationProcedure, so we will use that for interfaces.

This document was created by Serguei Mokhov on June 3, 2003
Last updated: $Date: 2007/08/03 02:44:04 $