Posted Wednesday, November 5, 2008 by
PJ Hinton
Sometimes you want to go
Where everybody knows your name
-- Gary Portnoy and Judy Hart Angelo,
"Where Everybody Knows Your Name" (a.k.a. Theme from Cheers)
Over at
Dr. Dobbs Code Talk, Christopher Diggins has an excellent post about the
importance of coming up with good names when writing code. He opens up with a brief anecdote to make his point:
It seems much of my time programming is spent trying to come up with meaningful names for things. I recently observed a problem that arose when two things were given the same name in a library, but that were in fact different. I was trying to document the library's functionality, and it turns out that virtually everyone on the development team was confused as to what it really was. Breaking apart the concept into two names, instantly cleared everything up.
I've seen this problem come up many times in my 11 years as a software engineer. It's a side-effect of the imprecision of everyday language.
The eight years I spent developing software at Wolfram Research exposed me to a corporate culture where the precise use of terminology was heavily emphasized.
Their flagship product,
Mathematica, is a high end technical computing package that has at its foundation a vast, eclectic programming language. Not only does it support different programming paradigms (procedural, functional, and rule-based), it also has to straddle concepts from disparate domains like computer science, applied mathematics, physics, graphics, and typesetting.
As a simple example, consider the term
trace. In linear algebra, "trace" refers to the sum of the elements of a matrix's diagonal. In software development, the same term refers to a record of function calls by a program. Since
Mathematica is a program that can record its evaluation history and do matrix algebra, the language had to support both notions.
To resolve the collision, there was a compromise, with the keyword
Trace becoming the function that was used to track the execution history of an expression evaluation, and the keyword
Tr being used to denote the linear algebra operation. It's worth noting that in making this distinction, the developers had to make an exception to another rule for the language, which was to shun the use of abbreviations in keyword names.
In my last job, I had interaction with members of the complex event processing community, an emerging field of applied computer science which deals with the modeling and creation of algorithms that can make decisions based on patterns of observed data. They are only beginning to coalesce around some
common terminology for things that we don't give much thought to, such as what exactly is an
event?
Here at Compendium, we grapple with getting the terminology right in the day-to-day design and implementation of our blog hosting software. Usually these are things we can hash out with quick meetings and a whiteboard. At other times, there is a need to be more formal.
For example, during one of our strategic sprints, we did a complete redesign of the default template used for our customer blogs. To make the style sheet easy to learn for web designers, we sat down and mapped out the layout of our pages and standardized the terminology of the elements, creating an
ad hoc, yet very useful, ontology.
Going back to my
previous post about web APIs, the need for consistency and precision in terminology is very important. APIs have both functions and parameters that serve as inputs to the application, and they have names to identify them. When a group of APIs uses names inconsistently, it makes the learning curve much steeper, and opens up the possibility of bugs due to programmer confusion.
As for Diggins' post, it wraps up with the following recommendations:
As a closing thought, the following are some of the different naming
sins that I frequently see in big libraries in no particular order:
overloading of names - sharing a name between two different items
incomprehensible names - "quux"
vague names - "Object", "Do", "Run"
missing names (e.g. using ints instead of enum, using literals instead of constants)
using comments instead of names
In the field of software development, a good name can sometimes seem like everything.