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.1 $

$Date: 2005/05/28 04:51:58 $

Brief Intro
Hungarian Notation
Project Coding Conventions

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:

code that is understandable only by someone who is very determined, and
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

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

Examples:

class Gun {}
class ThisIsMyClass {}
class AbstractSyntaxTree {}
class Dictionary {}

Method Names

First letter of every user-defined function is in lower case;
If the function's name has multiple words every other word should be capitalized;
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;
Name of the function has to have a meaning, obviously.

Examples:

getStudentName(); - is a getter, where strStudentName is a data member of a given class;
crashWindows();
die();
setMoney(Money poMoney);

Variable Names

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).

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

Class Structure

Each class has to have the following structure:


/**
 * javadoc comment goes here to describe the class
 * @author Serguei A. Mokhov
 * @since 1.0
 * @version $Revision: 1.1 $ $Date: 2005/05/28 04:51:58 $
 */
class MyClass [ extends WhateverClass ] [ implements WhateverInterface ]
{
	/*
	 * ------------
	 * Data Members
	 * ------------
	 */

	/**
	 * Just a Name
	 */
	private String strName;

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

	/**
	 * Constructor
	 */
	public MyClass()
	{
	}

	/**
	 * Performs some cleanup, e.g. closing files/releasing resources
	 */
	private void cleanUp()
	{
	}


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

	/**
	 * Retrieves name
	 * @return Name of the object, String
	 */
	public final String getName()
	{
		return this.strName;
	}

	/**
	 * Sets the name of the object. Name must not be empty.
	 * @param pstrName Name of the object
	 * @exception RuntimeException thrown if the name is an empty string
	 */
	public final void setName(final String pstrName) throws RuntimeException
	{
		if(pstrName == null || pstrName.equals(""))
			throw new RuntimeException("Name cannot be empty.");

		this.strName = pstrName;
	}

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

	/**
	 * Computes something of extreme importance
	 */
	public void computeSomething()
	{
	}
}

Bracketing
Opening and closing scope (curly) brackets should be at the same indentation interval, one under another:
```
void blah()
{
	for(;;)
	{
		if()
		{
			...
		}
		else
		{
			...
		}
	}
}
		
```
Indentation & Spacing
- Each beginning and ending of a scope should have some indentation interval (i.e. size of tab symbol; see the example above). Source code formatting uses a 4 column tab spacing, currently with tabs preserved (i.e. tabs are not expanded to spaces).
  
  [INSERT on HOW TO SET 4-SPACE TABS in different IDEs HERE]
- There should be at least one space line before each scope if there are many for() or while() loops for example, or if() statements.
Comments
Comments should be meaningful and precede the line they are referring to; they should not be on the same line.

Putting all together:

/**
 * Class Gun that fires.
 * Provides ability to set index and fire.
 * @author Gun Shop
 * @version $Revision: 1.1 $
 * @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

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;
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: 2005/05/28 04:51:58 $

Naming & Coding Conventions

Table of Contents

Brief Intro

Hungarian Notation

Simplified Hungarian Notation for the Team

Common Naming Rules

Class Names

Method Names

Variable Names

Method Names vs. Variable Names

Constants

Other Coding Conventions

Static (Class) Variables and Interfaces