Code is far easier to maintain if it uses real names to identify variables. A real name is one that describes what the variable represents rather than what type it is.
Avoid using arbitrary or generic words (including abbreviations of them) on their own in the code. Some commonly seen naming mistakes are shown below.
:
private static final int HOUR_CONSTANT = 1000 * 60 * 60;
private static final int ORDERS_CONSTANT = 40;
:
The word CONSTANT by itself does not convey more information to the user about what the constant represents. Final variables are constants by definition, so it is redundant information. Use the name of what the constant represents instead, in upper case.
:
private static final int MILLISECONDS_PER_HOUR = 1000 * 60 * 60;
private static final int MAX_ORDER_ITEMS = 40;
:
Variables too can have unneccessarily long names that add little value:
public int updateStatus(String nameVariable, int statusVariable)
{
:
return resultVar;
}
Since all variables are already variables, drop the word “Variable” and use the real name instead, even if it is only a temporary variable or simple string.
public int updateStatus(String itemName, int recordStatus)
{
:
return lastUpdateResult;
}
Avoid using the word 'type' on its own because it does not convey enough information about what kind of type it is. In some databases it is also a reserved word, so java object-to-database mapping will be confusing.
public class Order
{
private int type;
private Date date;
:
}
In the above case, the word 'order' should be included to clarify type.
Also, a field called 'date' is too vague; dates relate to an event that happens rather than to the order itself. So, the example is better updated as below:
public class Order
{
private int orderType;
private Date submitDate;
private Date paymentDate;
private Date deliveryDate;
:
}
By convention, 'input' or 'in' is OK to use if it is in a self-contained stream reader loop where it represents the input stream. But if the input reference is being remembered or passed around, it is better to state what kind of input it is. The same applies for output. State what kind of input or output it is if it adds some readability.
private Label parseForLabel(InputStream input1, File input2)
{
:
}
Sure, the Javadoc can give clearer information or the calling code can be analyzed to find what kind of values are passed in. But the java method is more readable when the InputStream is given a real name.
private Label parseForLabel(InputStream orderFileInputStream,
File addressXmlInputFile)
{
:
}
The count keyword is seen often without neccesary qualification.
:
if (wasRecordCreated(returnMessage))
{
count++;
}
if (isErrror(returnMessage))
{
count2++;
}
else
{
count3 += returnMessage.getItemWeight();
}
:
Using the count keyword in a very simple and obvious loop is reasonable, but in all other cases use more explicit language to explain what kind of count it is.
:
if (wasNewRecordCreated(returnMessage))
{
createdRecordCount++;
}
if (isErrror(returnMessage))
{
errorCount++;
}
else
{
// Hey, not a count after all - it's a total!
totalOrderWeight += returnMessage.getItemWeight();
}
:
