Avoid Perpetuating These Things In Your Code

Clayton Neff Programming 4 Comments

At some point in your career you will find yourself leaving the project you’re on and heading to new challenges (for better or for worse). Whether that is you taking another role with a different company or team, or if it’s the company you’re with outsourcing that project to other teams or even to another country.

Regardless of the reason, there’s a pretty big chance that at some point, you won’t be around to explain your code. Having worked on a variety of projects throughout my career, and with several programmers in other countries, I would like to present to you some tips for things to avoid using in your code to make the transition to other teams and non-native English speaking programmers less difficult and costly.

All of them are real life examples of code I have seen (and, unfortunately, occasionally written). Please take it as examples of things you want to avoid perpetuating.


This is about as ubiquitous as you can get. Everyone likes to use abbreviations so they don’t have to type as much. Unfortunately, most people don’t realize how much harder they are making debugging their code for programmers not “in the know.”

For example, you are writing a system to move money around the international banking system. There are hundreds of different types of transfers that you have to deal with. Rather than type transfer over and over, you use the abbreviation xfer instead.

Have you ever looked up xfer in the dictionary? Whoever is trying to take over your code might not be able to find it either! The more obscure the abbreviation (any of you know what “Penna” is short for?) the harder it will be for someone else to understand your logic.

Numbers As Words

This one is common as well, especially in languages that limit the length of your function names.

You want to write a method that converts a business object into a string to spit out in a file, so you call it cnvrtObj2Str. This has the advantage of using abbreviations (as mentioned above) along with substituting the number 2 for the word “to.” Imagine if you see a “2” and think “zwei”, what would cnvrtObjZweiStr mean to you? Especially if you are struggling with the abbreviations already.

This is even more difficult if the other programmer doesn’t natively use arabic numerals either.

Cultural References

This one is much less common, but still a problem. I worked on a project that allowed the user to put boilerplate contract clauses together to make a document specific to a particular customer, but made from text already approved by the legal department.

Soon the need for legal folks to create new clauses arose, so a new project was started. Since this project was basically a helper application for clauses, the American-centric team called it ELF (Santa Clause’s helper, get it?). To help differentiate the code between the two applications, elf packages were used, as well as having the word ELF in a lot of class names.

When the time came to transfer the coding responsibilities to another team from a different culture, there were several discussions about what ELF stood for. Despite explaining multiple times that it didn’t stand for anything, that question came up time and again.

Another example was in some Java code that was processing a lot of collections. The programmer was trying to use logical variable names for his iterators, but eventually got worn down by all the repetition. So lo and behold, the code became scattered with declarations like: Iterator schmiterator.

While the code was still understandable, other programmers unfamiliar with the cultural reference had to stop and think about what they were looking at later in the code. It was less intuitive for them when they saw schmiterator.next(). They had to stop and think “What is a schmiterator, and what it is giving me the next of?”

Real World Solutions

Modern development environments provide help in the form of content completion. Rather than abbreviating your names, or using numbers instead of words, spell things out. When you need to reference them later, the IDE will do most of the typing, and you’ll be sure to get the right name all the time.

After all, when you are reading the code 6 months from now, which will be easier for you to understand, cvrtRur2Usd4Xfer or convertRublesToUsDollarsForTransfer? Be kind to your future self.

Finally, don’t get cute. We all get bored, and we all share inside jokes with others on the team. But what is cute and funny today may look childish and sophomoric later. We are supposed to be professionals, we not only should we act like it, our code should look like it. Exposing those jokes in our end result just isn’t a productive use of our time. And after all, isn’t that what we are all shooting for, to be more productive? Because the quicker we are done, the quicker we can get home and spend more time with our families.

Final Thoughts

We are all responsible programmers who want the person that has to take over our code to stress about it as little as possible. After all, we have had to take over other people’s code in the past, and we will have to do it again in the future. So pay it forward and avoid all these situations.

— Clayton Neff, asktheteam@keyholesoftware.com

P.S. My editor said “I will be using schmiterator sometime in the future, but I’m going to abbreviate it.”

About the Author
Clayton Neff

Clayton Neff

My first exposure to personal computers was in college when a friend bought an Apple ][. We had great fun altering Adventure to make it more surreal. I later did some tinkering with C and Assembler, but once I was introduced to Object Orientation, I never looked back. I had a series of jobs using various OO languages (all of which are defunct now except C++) before I started working primarily in Java. When not traveling back in time as a Medieval recreationist, I enjoy traveling the world. There are few things sadder than an empty passport (one being not having one).

Share this Post

Comments 4

  1. Well-stated! I have sometimes wondered if people think that letters cost money and that is why they use abbreviations and acronyms.

    A related “hot button” for me is writing a Javadoc comment for every public method (and many of the protected ones also). I have the compiler options tightened down to make me obey my better self. 🙂

    1. Thanks Jay.

      I have a friend who has an email signature that says “No trees were harmed in the creation of this email, but thousands of electrons were inconvenienced.” That must be how people feel about having too many letters in their code.

  2. I suppose that, since your article considers programmers from many nations, that any dates in Javadoc or comments should take that into consideration. Like “5 Mar 2015” to avoid reading “3/5/2015” as May 3, 2015.

    To illustrate your point further, I worked on a system where they actually had methods called “dummyMethod” that was called from many places in the code, but was provided in a black-box library. Curious, I decompiled the library and it ended up being a no-op. That same system had a “dummy” column in several tables in the database, which meant different things to different sections of the code. I prayed for something as clear as “schmiterator!”

Leave a Reply