Meaningful Names

If you should take away at least one thing from this course, it should be this: give your variables, functions and classes meaningful names. Let me explain... First you need to know what a name should do:

• It should tell why that variable exists
• I should be able to tell what it does
• How I am going to use it in the code

As a rule of thumb I say that if a variable requires a comment next to it to tell me what it does, then the variable itself does not reveal intent. So your readers will hate you. Let me give an example.

Think to yourself, what does this variable do: int d;

I have no idea what it does. This is because the name "d" reveals nothing to me. Nothing! It does not evoke a sense of what it is supposed to be doing. Here would be some better names

int elapsedTimeInDays;
int daysSinceModification;

The second suggestion of the name is far 'cleaner' as it provides more context and makes your intent clearer in your code. We also know that it is a variable because of our use of lowerCamalCase. You may be thinking "That is a long variable name to have to type every time I want to use it!" Yes, it is long. However most text editors offer tab completion. So you can simply start typing the variable name and your editor should narrow down the options for you to choose from and you simply press 'tab' for an automatic completion.

Let us look at this idea with an example. So, looking at the code to the right, can you tell me what it does? Have a minute to think... Done? I don't know either. This code is very difficult to decipher with poor variable names like x, list1 and getThem(). We have no way of telling what the purpose of these variables and functions are. Also, what is the significance of the number 4? Why is important if it is equal to x[0]? The problem with this code is not its simplicity but its implicity.

public List getThem() {
	List list1 = new ArrayList();
	for (int[] x : theList)
		if (x[0] == 4)
			list1.add(x);
	return list1;
}		

Now I have made some changes to this example. Is it any clearer what it doing yet? The variable theList has been changed to gameBoard which provides so much more context to what it is we are working with. We now also know why the number 4 is so important. It represents a status value of being flagged. We also understand that the interger array x represented a cell and that the different integer array values corespond to status values. These are likely defined elsewhere in the code using an enumerator class.

public List getFlaggedCells() {
	List flaggedCells = new ArrayList();
	for (int[] cell : gameBoard)
		if (cell[STATUS_VALUE] == FLAGGED)
			flaggedCells.add(cell);
	return flaggedCells;
}		

Even though the above code is good, we can do better. Here we can see that a simple class called Cell has been created that handles out integer arrays (int[]) and it also includes a function that checks whether our cell is flagged or not, thus cleaning up the, quite frankly, garish cell[STATUS_VALUE] == FLAGGED line of code. So with these simple name changes it is not difficult to understand what is going on. This is the power of choosing good names! By the way, if you haven't figured it out yet, this is a line of code used to make a Minesweeper styled game.

public List getFlaggedCells() {
	List flaggedCells = new ArrayList();
	for (Cell cell : gameBoard)
		if (cell.isFlagged())
			flaggedCells.add(cell);
	return flaggedCells;
}