In a previous article, we explored the reasons for bad variable naming. In this article, we’ll look at why your basic spelling and grammar skills are important, and using your context-based linguistic skills in reading code.
Frankly speaking, you just need basic spelling and grammar skills. I mean, it’s not like you’re asked to code stuff about the number of defenestrations or keeping track of myocardial infarctions. Unless, of course, you’re working on a medieval game where throwing people out of windows is fun or a medical application predicting the likelihood of heart attacks.
For the most part, you’re working with concepts such as user IDs, names, sums of something, billed amount, tax amount and so on. These concepts are likely to be commonplace. If not, they would be explained in a business document. The hard work of naming variables is already done. You just need to name those variables. How hard can
All you really need to take care of is spelling and simple grammar. Why spelling? It’s easier to read and it’s easier to find. Imagine you need to do some refactoring, and you have to replace all references to “Result” to “Case”. You thought your find-and-replace was done. Then you find an instance of “Rslt” or worse, “Resutl”. The worst part is you don’t know if you’ve completely replaced every instance correctly, including those weird cases.
As for grammar, let’s look at the simple case of plurality.
GetResult() suggests the return of a single record.
GetResults() suggests the return of possibly more than one record, maybe a list or an array. An unimaginative programmer might name the second function
GetResult2(), which tells us nothing whatsoever, other than it’s possibly another form of
This reminds me of something baavgai from Dream In Code said about naming database tables and columns. If I remember correctly, he suggested using the singular form, for example, “customer” for the database table storing customer information. This way, the “customer_id” column makes sense, instead of “customers_id” in the “customers” table. Even if the computer doesn’t care either way, please use appropriate singular or plural forms, for the sake of other human beings.
If spelling errors and inappropriate forms in code are travesties, spelling errors and inappropriate forms in database tables and columns are abominations! The database is the backbone of everything you code. If a table name is changed, can you imagine how many applications are affected by the name change?
Back-end programs, console programs, web applications, stored procedures. Every single one has to be checked and corrected. It just takes too much effort, so the table name remains incorrectly spelled.
Let’s go back to spelling for a bit, in particular, short forms or abbreviations. Don’t use them. Spell the word in full. Not everyone can decipher
decBillAmt as billed amount (take note of tenses too). If the shortened form is widely known, or reasonably well known within the context, then by all means use the short form.
There was this time where a senior level manager was reading through the documentation to find out more about the nuts and bolts of our application. He stopped at
AcctNo. He asked, “What’s account no?” He managed to decipher “acct” as “account”, but couldn’t make head or tail of what “no” means. The negative of “yes” didn’t fit the context. We had to explain it stands for “account number” in full. Shortening words for the sake of short forms is not an excuse for illegibility.
There’s also this instance where my colleague asked me what
mstIptRec was. I thought for a bit, racking my brain for the business logic involved, scouring the surrounding code for clues and sifting through my vocabulary to fill in the missing letters. I came up with “master input record”. Make your fellow programmers’ lives easier; spell the word in full.
Filling in gaps
Nothing has meaning except the meaning you give it.
This brings us to the next point, understanding your fellow programmers’ code. You may be a skilled programmer, but the sad truth is, you’re going to read other people’s code, and let’s face it, some of them are terrible.
You are able to understand what “i can has cheezburger” means because you can rearrange words and fill in letters. Your problem with code is that, well, the compiler has already “approved” the other person’s code. You know, by successfully compiling it. The compiler has already understood perfectly what the code has to do. You’re the one who’s in trouble.
Since the syntax (grammar) is correct, and the spelling is correct (compiler will have choked on “
ant i;“), you have to look at the variable names, function names, class names and so on to decipher meanings. This is where your linguistic skills come into play. You need to fill in the context. This is crucial to your quick understanding of another person’s code, maybe even your own.
Compilers are incredibly unforgiving when it comes to syntax, yet unbelievably forgiving when it comes to context.
Remember, you’re the only one who knows if
int i = 2 + 3;
int i = 2 * 3;