In any programming language,
With such strict rules in place, you would think that it would be easy to pick up someone else’s code and understand immediately what is going on, right? Unfortunately, that’s rarely the case. There are three main areas that are the source of contention among developers (and corresponding confusion). They are variables, comments, and structure. I’m going to address variables today.
In nearly every modern language, developers can name variables as they see fit. In the communities for each language certain standards have evolved, but they are rarely followed completely. Let’s look at some of the issues.
Consider a piece of code where total cost needs to be calculated by multiplying an item’s cost by the quantity of the item. If we are familiar with what has happened elsewhere, including variable declarations and purpose of the code, this might make sense:
t = q * c;
If you came across it without any context, you would likely have to figure out what is happening. The following might be more helpful:
Total = Quantity * Cost;
This would at least give a better understanding of the action being performed. Other issues might emerge because the variables are named according to the developer’s preference and remain open to interpretation. For example, is the “cost” depicted above the cost to the consumer or to the merchant? Big difference to the eCommerce company relying on your code to show the right price to its online shoppers.
It doesn’t help that other conventions can be thrown into the mix, like Camel case, Hungarian notation, prefixes, word separators, and special abbreviations. I remember a situation many years ago where a client had a difference between acct_nbr, acct_num, and account_nmbr. The folks who worked in that code even pronounced them differently (“Nibber”, “Numb,”, and “Number”) to avoid confusion.
In an effort to address some of these issues, certain groups have issued guidance. Microsoft discourages the use of Hungarian notation, for example. There are countless factions with strong opinions on what the “right” conventions are, with arguments for and against bordering on zealotry. When coding, there is nothing to stop a developer from doing whatever he or she wants, including things like this, a real-life example of code seen in the wild:
SesameStreet = Cookie * Monster;
Good luck trying to figure that one out. I’m certain you have come across similar silly and seemingly harmless code that’s ultimately not helpful at all.
Clean Up Your Language
Have policies for nomenclature and conventions set at the organizational level. The specific policies are less important than making sure they meet the needs of your environment and that they are enforced. When everybody knows the rules, there should be no misunderstanding. And not publishing the rules is like having no rules at all.
Conventions should be owned by the CIO or an equivalent leader in Information Systems. Feedback can (and should) come from anywhere but once the rules are set, they need to be followed and enforced. Only a senior leader will be able to keep the Cookie Monster at bay by setting expectations. Use code reviews and acceptance testing to help maintain standards.
Sure, situations will emerge that require adjusting the rules as you go along, but at least you’ll have guiderails in place to evaluate each instance. There’s also the question about what to do with all the code written before the standards. It usually doesn’t make sense to go back and change all the legacy code. Address issues as they are discovered to determine the level of effort to bring them into compliance. Part of that process is including information to help other developers who encounter the code, like comments in the code.