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.
Abbreviations
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.
P.S. My editor said “I will be using schmiterator sometime in the future, but I’m going to abbreviate it.”
| Reference: | Avoid Perpetuating These Things In Your Code from our JCG partner Clayton Neff at the Keyhole Software blog. |
