The Fairway Technologies Blog

blog

Stp Abrvtng!

When I started out as a wee programmer back in the 1980s, “Hungarian Notation” was all the rage. Invented by Charles Simonyi (a Hungarian guy!), it espoused a naming convention for variables that included the intent (or kind, or type) for that variable. Unfortunately, the semantic meaning of type is overloaded, and many developers assumed it meant “data type.” So, you had variables that were clearly string variables called strFirstName or clearly integer variables called intCount. In a type-safe compiled language, this is redundant, but many Microsoft devs, myself included, blindly followed the pattern because we learned it, and it made sense on the surface.

Screen Shot 2018-11-20 at 3.06.02 PM

In the 90’s, I cut my teeth (literally?) on Perl programming, and it was in vogue at the time to show off how concisely you could get the job done. Perl is powerful and arcane, and there are “obfuscated Perl” contests where devs attempt to out-confuse each other, and nod-and-sniff knowingly when they don’t:

Screen Shot 2018-11-20 at 3.07.24 PM

As my career progressed, I worked in a variety of languages with very different approaches to naming conventions (at least in my exposure to them):

  • Visual Basic and Delphi: Hungarian Notation
  • C and C++: “standard” abbreviations for common idioms (e.g., num, avg, init, temp, in, a, b, x, y, etc.)
  • Java: verbose to accomplish basic tasks, so developers tended to abbreviate variable and method names (e.g., empId for “Employee Identifier”)
  • Oracle: 30-character table limit, and the insane practice of prefixing table names with “T_” (e.g., “T_INV_TRX_LDGR”)
  • JavaScript (before minification was a thing): keep variable and function names short because every byte adds to the page download size!
  • .NET/C#: still some vestiges of Hungarian Notation left over, but a willingness to create more descriptive variable and method names

Screen Shot 2018-11-20 at 3.09.38 PM

As I worked in all these different languages, I was regularly reading code written by other people, and I was frustrated most of the time because I had to unravel the abbreviations other developers had used in their code, which were pretty inconsistent. Well, except for the fact that almost all developers felt the need to abbreviate (to save time typing perhaps?) … in that way, they were consistent.

As Uncle Bob said:

“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write.”

When I first started doing Test-Driven Development (TDD), I came across Roy Osherove’s “The Art of Unit Testing,” with the following convention recommended for naming unit tests:

[UnitOfWork_StateUnderTest_ExpectedBehavior]

This pattern led to method names like:

BankWithdrawal_WhenAccountOverdrawn_ShouldThrowNonSufficientFundsException

I made that intentionally long, but that was a pattern that kind of took off in the community, because it helped organize tests when they were run, and was very readable when a test failed. When I first saw this, I thought, “you can do that?” I had seen so many examples of when long names caused problems (Word-wrap issues due to 80-character line limit in old terminals, Windows API 260-character file path limit, etc.) that this seemed like codemageddon.

Then I just started getting way more descriptive in my class, method, and variable names, across the board, and I was much happier. In any situation where I felt something could be misinterpreted, I would clarify not by adding a code comment (though they have their place), but by improving the name of the variable. So instead of:

GetCrdAuths(int id, int type)

My method might be:

FindAllEligibleCardAuthorizations(int merchantNumber, SettlementType settlementType)

Yes, more typing, but the intent is so much clearer, and it really makes you think about what you’re passing into the method, and why. In IDEs that offer code completion, like Visual Studio and IntelliJ IDEA, this saves so much time.

Here’s an example of a file naming convention I used for JavaScript files on another project:

Screen Shot 2018-11-20 at 3.14.00 PM

Each dot in the path represents a more specific component. I could have just named the last file “dateRangeView.js” but the context of where the file fit into the overall component hierarchy made searching way easier. There were also “date range views” related to other components, so this helped to differentiate them. And now that we have stable and predictable minification as part of the JavaScript build cycle, you can go nuts with long variable and function names and not impact your users.

Here is another example I pulled from one of our codebases (with minor tweaks) to show the readability of long variable and method names. To me, it’s very clear what this code does, even though I haven’t looked at it five years.

Screen Shot 2018-11-20 at 3.15.02 PM

Of course, there are times when abbreviations make sense, because they are so common that it would be confusing to make a longer variable name. Two classic examples are using “id” as an abbreviation for “identifier,” and using i as the index variable in a for loop. I’ve definitely used the full word “index” instead of at times, but if you’ve ever written code,

for (var i=0; i < items.length; i++)

should be very familiar. And if you are using nested loops, is okay too.

But if you are using one- or two-letter abbreviations to save keystrokes, it’s just going to confuse you later. If you’re working with a collection of employees, it’s not e, or empColl, it’s employees! If it’s plural, you know there’s more than one. Even three-letter abbreviations can get you in trouble. We had a project with the concepts of “contact,” “content,” “context,” and “connection,” and if you used the abbreviation “con” you were completely lost. If I have a method that returns a list of airport names for a city, I’m going to call it FindAirportNamesByCity(string cityName), not GetApts(string city).

You get the idea…

So, I am imploring developers to avoid abbreviating whenever possible. Err on the side of too many words in your variable names, then dial it back until it might not make sense to a brand-new developer. There are reasonable limits, which you will discover when working on a team that has the same philosophy and goals, but those brand-new developers will be able to ramp up much more quickly if they don’t need to mentally expand those abbreviations.

New Call-to-action

Sign Up For Our Monthly Newsletter

New Call-to-action