The Rules of Programming

Rule 3. A Good Name Is the Best Documentation

You can’t write about programming without quoting Shakespeare, obviously. It’s sort of a cliché at this point. Nevertheless, here’s Romeo and Juliet, a quick recap: Romeo and Juliet are star-crossed teens in love, prevented by the enmity between their two families from spending a joyful life together. It ends poorly for all involved.

Act II, Scene II. Juliet bemoans the situation in the fifth-most famous quote from the play:

What’s in a name? That which we call a rose By any other name would smell as sweet

I’ve heard similar arguments made about code, typically by colleagues frustrated by my persnickety code review attitude toward how stuff is named. Variables, functions, members, source files, class and structure names—I’ll quibble about any of them.

People will argue, typically with an eye roll, that the name doesn’t really matter, that what matters is the thing named. The true meaning of the variable (or function, or class, whatever) can only be determined by looking at the code. The truth of a variable is what it represents—how it’s set, how it’s used, not what it’s named. The functionality doesn’t change if the name is changed.

So, they declare, just choose something easy to type and get on with coding.

These people are wrong.

The name of a thing is the first and most important documentation you have. It’s inescapable. It’s always there. Whenever you see any sort of reference to the thing, it’s by its name. That continual presence ...