⇥ You are not “Mr. X”
I keep coming across code like this (lifted, verbatim, from an OSS project I’ve been working with recently):
$a = $num * $coeff + $_SANITIZED_GET['val'];
What, in the name of all that is good and just, is “a?” Or, for that matter, what are “num” and “coeff?”
Computer manufacturers, OS vendors, and programming tool developers have worked for decades to give us the ability to create identifiers of arbitrary length. Personally, I’d much rather see someReallyLongNameThatLooksALittleRidiculous than a function or variable name that won’t tell me what it does at first sight.
The same goes for data. A “1” and “0” in a database don’t tell you as much as “Yes” or “No,” which are just as localizable, indexable, and searchable. Enumerations, as far as I’m concerned, should be verbose unless there are very compelling space or performance requirements that say otherwise.
I know that there are many people who disagree with this approach, but their arguments tend to fall in the “that’s the way I’ve been taught to do it” camp. The reality is, a numeric enumeration is just as arbitrary as a string-based one, but much harder for the human eye to make sense of—and we all know that, sooner or later, all data is looked at by a human eye. There are some circumstances in which performance and space constraints come into play, but otherwise the development tools at our disposal are mature enough to handle either type as easily as the other.
Besides, using numbers to identify non-numeric value is a domain violation. It used to be a necessity twenty years ago, but the vast majority of us work in environment that are well past that point. You wouldn’t want to be called “492829,” right1?
So, if you are writing a book or teaching a course on programming, please teach your readers and students to write descriptive code. They’ll be better for it, and we’ll be grateful that you did.
- Yes, I know. You probably have some kind of social security number assigned to you by your government. But that’s not your name—it’s an index (that is, a numeric value) in a table that *contains* your name. Big difference. ↩
Comments
The one thing I would say I do like using ‘Yes’ or ” for Boolean values in a database with a suitable name for the column. That way in certain languages you can simply treat them as a Boolean.
I agree with you Marco. However I don’t agree with the absolute nature of your statement. As a general rule of thumb, yes, PLEASE use descriptive variable names.
However, there are cases where $a makes all the difference in readable code.
Specifically I’m thinking of cases where you are assigning the variable, and only using it in the next 2 lines of code, but those two lines of code are longish, complicated-ish, and having a shorter variable name makes them MUCH easier to understand & parse.
However, that is a very specific use-case, and should only be used for those ‘couple lines of code’, and 50 lines of code later you better not ever be referring back to that $a.
Yea I don’t have a problem either with short variable names, as long as they are limited to the scope of a function. I tend to especially do this for ‘for’ loops.
But rather than using $i as the index, use $ii so it’s search & replaceable.
I’m with Eli and Evert on this, I like descriptive for variable that are in a large scope, however if they have a very limited scope, short throw-away names like Evert said are fine. In your specific cited example, $a is completely unreadable. I could grok num and coeff, even val to an extent however, wtf is $a? For that matter, I don’t understand what the formula could be doing and would rather have a method call with those params. Or is that taken from the method call? Even so, I’d want a descriptive name for $a so I know what’s being returned at a glance w/o looking at the method.
“Yes” is not a boolean value so you end up with idiotic code like `if ($deleted === ‘Yes’) {/**/}`.
Variable name lengths have a perfect rule of thumb. A variable length should be proportional to the distance between its usages and definition in source code.
>But rather than using $i as the index, use $ii so it’s search & replaceable.
dear god, please get an IDE capable of refactoring and/or stop using globals.
I work on sites that have to be multilingual, so therefore, we use binary values in the database for 0 and 1 for No/Yes, False/True etc… Then when we display the value to the user, then the language can translate the variable without everyone having to understand the different languages in a table.
The short variables do bother me to, unless they are a loop variable (i, j, etc…) which is a common convention. I disagree with Eli where the simple variable for 2 lines might work so you can see it all, but with multi-line statements in IDEs, it is still okay to use something meaningful.
How about some notation while we’re at it? Just because a language isn’t type strict doesn’t mean it’s important to know what values to -expect- in a var… $aBananas vs $nBananas can make a huge difference in reasoning when dealing with a foreign codebase
I don’t personally have a problem with short variable names in a math context when they map onto standard textbook notations. A linear equation, for example, is y = mx + b so if I see $y = ($m*$x) + $b I’d prefer this to any long hand you might come up with. I agree longer descriptive variables names are generally good, but mathematical programming is the exception for me.
If the project is very dinamic and does not use any super-smart ORM or migration system then dealing with boolean column is NOT done the way you are talking about:
Today it is Yes/No.
Tomorrow it becomes Yes/No/Maybe.
The next day – Yes/No/Skip.
In some environments it’s just hard and slow to apply database column info changes. It is much faster to define one more constant like this: Entity::SKIP = 3; and keep going faster… without touching neither database management software nor migration system.
It is the real case in my project and I have to deal with it.