Recipe 2.6. Establishing a Naming Convention for Your Variables

Problem

You need to follow a dependable pattern for naming variables in your web site scripts.

Solution

Develop coding guidelines that make sense to you, your team, and your web site, and then stick to them.

In general, a good variable naming scheme:

Uses unique, concise terms
Limits abbreviations
Avoids reserved words in its programming language
Serves as a form of self-documentation

Discussion

Variables are used to store alphanumeric values that will be manipulated by a script or program. Variables can have a constant value defined permanently in the code, or be changed from one value to another through logic or input from a user.

For example, a PHP script might take a Fahrenheit temperature value entered on a web site form (call it $temp), perform a calculation on the variable to convert it to Celsius, and then echo the same variable (with a new value) back to the user.

The variable name $temp has several disadvantages (that's why I chose it). As a generic abbreviation for temperature, $temp easily could be misconstrued as representing a temporary value (or the user's temperament) by another programmer reviewing the code.

If you find that you have to use abbreviations or shorthand for your variables, compile a glossary and add it to a central comment block in your script.

While the name $temp meets the simple needs for a hypothetical temperature converter, it becomes woefully inadequate as soon as you try to add other functionality to the converter. Say, for example, that you improve the script to accept two temperature values from a userthe current indoor temperature and the current outdoor temperature. Which one of the two should be $temp? Neither. A better strategy is to use more meaningful names for the two variables, such as $indoor and $outdoor.

Now, let's suppose that you want to let users specify how to convert the temperatures: from Fahrenheit to Celsius or from Celsius to Fahrenheit. For this, the script will need another variablewhose value is chosen by the user through either a radio button or select menuthat dictates which conversion to perform on $indoor and $outdoor. Let's call it $convert.

So far, so good. Two temperature values and a trigger value ($convert) go in, and two new temperature values come out. But wait: now let's add the ability to convert atmospheric pressure readingsfrom inches of mercury to millibars or vice versa at the same time for both indoor and outdoor readings (Our hypothetical user has a great weather gauge!).

Now the script needs six variables: two for temperature, two for pressure, and two for the types of conversion to perform. And now you should start to see why having a naming scheme can be valuable. Six good variable names for the converter would be:

 $indoor_temp; $outdoor_temp; $convert_temp; $indoor_pressure; $outdoor_pressure; $convert_pressure;

For PHP variables, I recommend using all lowercase letters with underscores separating words to improve readability. An alternate technique uses so-called camel case, or inner-cased, variable names, meaning that words in a name are capitalized (except the first) and run together without spaces$indoor_temp would become $indoorTemp.

The latter method has pitfalls because variable names in PHP (as well as JavaScript and Perl) are case sensitive. The names $indoortemp and $indoorTemp would represent two different variables. Whichever technique you choose, be consistent and avoid naming two variables whose names differ only by case.

Variable names for constants should be all uppercase, such as $EARTHS_ GRAVITY.

The uniqueness of a variable also can be affected by the order of the words in its name, which in turn can affect how well variable names "self-document" a script or program. Easy-to-read and understand variable names are critical for projects with more than one programmer (or for just one programmer who does not look at the code very oftenyou know who you are). For the six variables needed for the sample converter script, I chose names with better distinctiveness at the beginning of the name. Three variables beginning with $temp_ and three beginning with $pressure_ would not provide the same benefit to another programmer scanning the code to distinguish between adjacent references to two variables.

Problem

Solution

Discussion

See Also