Naming Names

We have all heard that good variable names are important for creating readable programs — advice that will serve you well when you come back to your code two years later, or even twenty. Sometimes, when you are so deep in the zone and begin to question a variable name that you made three levels up the calling hierarchy, it can be helpful to take a step back and review your variable naming conventions. The wikipedia article on computer program naming conventions is a good starting point, where you can dig into the nitty gritty of Hungarian notation like bFlag, case separated names like camelCase, and so on. But sometimes you have to go meta, and need names to describe the names themselves.

For example, in everyday usage the terms parameter and argument are often used interchangeably. But strictly speaking, a parameter is a placeholder, the variables in a function declaration for example (see image above). An argument is the actual value itself, say the number 50.334 in the example.

We recommend that units of measure should always be clearly specified in your comments, perhaps even in the variable names if you’re mixing different systems in the same program. At Hackaday we prefer to use SI units, check out NIST SP 330 if you’re interested. But invariably, there are going to be exceptions for years to come. We like to deal with those at the edges during I/O if possible, thus keeping a consistent set of units in the core of the program.

What about the terms number and value? We like to think of a number as being a kind of value. For example, a function’s return value could be a number, say a velocity. Or it could return an enumeration or a boolean. Sometimes the perfect meta-name for something will collide with a reserved keyword in your programming language, names like string or data for example. In these cases you have to be creative and find suitable synonyms, perhaps text and payload.

Using consistent and precise language can be tedious, but it can be just as helpful as good commenting and variable naming practices. Do you have any examples where precise terminology such as this has been been helpful or perhaps tripped you up? If so, share in the comments section below.