Code is Tricky, Part 4: What Code Says Is Different Than What It Does

Computer languages have an interesting quality not shared by many human languages: syntax is far more important than semantics. For example, in English, the sentence, “The colored clarifications eat
sharply” is syntactically correct, but semantically meaningless. Computer programs are all about having the right syntax based on the rules of the language, and as long as the same words are used consistently throughout the code, it doesn’t matter what those words are. Imagine a line of code for a banking program that reads:

availableBalance = currentBalance + lastDeposit

The above line of code would do the exact same thing if it were written as any of these:

karl_marx = kanye_west + wonder_woman

x9jbr20RNAxix = bleepblorp + doyouliketurtles

cake = sugar + flour

As long as the same terms are used in the correct locations, then the computer doesn’t care at all what those terms are. Still, choosing descriptive names is a good thing for a programmer to do. When a method or variable has a name that explains the data it works with, or what its role is in the program, it can save time and make the whole programming effort easier and simpler.

But there is an insidious problem that sometimes appears in the code: a variable or method name that has a descriptive name… that describes the wrong thing. This is especially tricky to diagnose because it’s an error that doesn’t look like an error at first glance. However, it’s actually hiding in plain sight.

For example, when a programmer sees a variable in a program named x, that name doesn’t tell the programmer anything obvious. They have to read through the code to see how x is used. It can take some time, but at least it results in some productive knowledge: they now know that x is a variable that stores, say, a name.

Now imagine the same variable isn’t called x. Now it’s called person_id.

A programmer would look at that variable, see the _id suffix, and assume (quite reasonably) that person_id stores an integer value. Because the name seems to tell them what kind of value is inside, they have no reason to trace how the variable is used. An incredible amount of confusion can easily ensue, as programmers tear their hair out revisiting assumptions about what the code is actually doing.

A good development team will have a standard approach for naming variables, methods, properties, namespaces, modules… anything that can be given a human-readable name should adhere to the convention, whatever it is. Those names exist solely for the benefit of the programmers. The benefits are only realized when they’re used consistently.

 

[ headshot of Jason Frankovitz ]
Jason Frankovitz

As a developer and CTO, Jason Frankovitz has been in the trenches of technology for more than 25 years. He has worked as a programmer, software development manager, technical analyst, CTO, and mentor in a wide variety of industries including enterprise software, digital entertainment, and Web-enabled government.