Naming conventions

From WikiJava

Choosing good names for the elements of your software is crucial for a good software developer, because it makes possible to read the code you wrote after some time and still be able to understand what it does and how. During the history of programming this topic has been greatly debated and studied. This tutorial gives some easy and effective guidelines on how to choose the names for the entities in your code.

the article

It is a best practice to always use the naming conventions for all your packages, classes, methods and variables.

The official java naming conventions are stated in this document.

The document from Sun contains the naming conventions for what can be verified in a correct or wrong point of view, there are several more rules which suggest how to choose the names in your code.

package names

The packages normally are in the following format:

com.<company_name>.<project_name>.<component_name>.<eventual_more_subpackaging>

where

com is the default prefix for software for commercial use

<company_name> is the name of the company the code is made for

<project_name> is the name of the project the code belongs to

<component_name> is the component of the software the code implements

<eventual_more_subpackaging> (optional) this may include many subpackages, and helps division of classes for their role.

examples

package com.wikijava.examples.naming
package com.wikijava.examples.naming.package.subpackage

variable names

The main rule in chosing the name for a variable, is to be sure that it clearly explains what the variable contains and why it is used.

the problem

Ideally no comment should be needed to explain what a variable represents.

Imagine the case in which you are reviewing a piece of code written by someone else, and you stumble upon a row like the following: We would not understand any of this if the row would have been:

String user = ses.getAttribute(mySes.U_NAME);

this row doesn't tell us much about the meaning of the variables or what they contain. We may realize that the result of the assignment is some kind of information about the user and that ses is a container of attributes. To understand what type is mySes.U_NAME we need to search it's declaration.

The same row could be written as follows:

String userName = httpSession.getAttribute(mySession.USER_NAME);

The same three variable appear here, only the names are changed

userName it is clearly a local variable containing the String representing the username

httpSession it is clearly an istance of

javax.servlet.http.HttpSession

containing the information about the servlet session, it is clear that we are into a servlet for the http protocol

mySession.USER_NAME knowing the Java naming conventions we understand that this variable is defined as static final and from the context it contains the String representing the user name attribute stored in the session.

Moreover, it is clear from that example that we should expect somewhere in the code above the row we are analyzing an import similar to:

import javax.servlet.http.HttpSession;

and a inizialization similar to:

HttpSession httpSession = request.getSession();

All this information is immediately understood from one single row of code.

the solution

We may try to express a rule of the thumb on how to choose variable names:

A variable should be called as the name of the interface it will accessed with if it is clear what the object contains for example:

HttpSession httpSession;

leaves no doubt about what the object will contain.

If the interface is not specific enough then we should choose a name more bound to the content, for example:

List<Customer> customers;

the variable customers is clearly a kind of set containing information about the customers. The use of this variable in the code will be much clearer.

The name of a variable should be bound as close as possible to the actual content of it

See Also

http://java.sun.com/docs/codeconv/html/CodeConventions.doc8.html

Comments from the users

To be notified via mail on the updates of this discussion you can login and click on watch at the top of the page