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.



There Is No Such Thing As An Invalid Unit

The Mars Climate Orbiter was a spacecraft launched in the closing years of the 1990s, whose job was to have been to study the Martian atmosphere and serve as a communications relay point for a series of other surface missions. It is famous not for its mission achieving these goals, but for the manner of its premature destruction as its orbital insertion brought it too close to the planet’s atmosphere and destroyed it.

The ill-fated Mars Climate Orbiter craft. NASA [Public domain].
The ill-fated Mars Climate Orbiter craft. NASA [Public domain].
The cause of the spacecraft entering the atmosphere rather than orbiting the planet was found in a subsequent investigation to be a very simple one. Simplifying matters to an extent, a private contractor supplied a subsystem which delivered a reading whose units were in the imperial system, to another subsystem expecting units in the SI, or metric system. The resulting huge discrepancy caused the craft to steer towards the surface of the planet rather than the intended orbit, and caused the mission to come to a premature end. Billions of dollars lost, substantially red faces among the engineers responsible.

This unit cock-up gave metric-using engineers the world over a brief chance to feel smug, as well as if they were being honest a chance to reflect on their good fortune at it not having happened on their watch. We will all at some time or another have made an error with respect to our unit calculations, even though in most cases it’s more likely to have involved a simple loss of a factor of ten, and not with respect to a billion dollar piece of space hardware.

But it also touches on one of those fundamental divides in the world between the metric and imperial systems. It’s a divide that brings together threads of age politics, geography, nationalism, and personal choice, and though it may be somewhere angels fear to tread (we’ve seen it get quite heated before to the tune of 885+ comments), it provides a fascinating subject for anyone with an interest in engineering culture.

Continue reading “There Is No Such Thing As An Invalid Unit”

What’s So Bad About The Imperial System Anyway?

As a Hackaday writer, you can never predict where the comments of your posts will go. Some posts seem to be ignored, while others have a good steady stream of useful feedback. But sometimes the comment threads just explode, heading off into seemingly uncharted territory only tangentially related to the original post.

Such was the case with [Steven Dufresne]’s recent post about decimal time, where the comments quickly became a heated debate about the relative merits of metric and imperial units. As I read the thread, I recalled any of the numerous and similarly tangential comments on various reddit threads bashing the imperial system, and decided that enough was enough. I find the hate for the imperial system largely unfounded, and so I want to rise to its defense.

Continue reading “What’s So Bad About The Imperial System Anyway?”