Sparks from a sparkler

Keep the Cookie Monster Out of Your Code

In any programming language, syntax is critical.  Everybody who has made it past their first “Hello World” program has experienced this directly.  If you’re lucky, the compiler tells you that you did something wrong and shows you where the problem is.  If you are less lucky, you may have made a mistake that compiles into something unintended and you’ll have to figure out the problem later.  Software developers know that there are rules to writing code, and an application will do specifically what it is told to do in the context of those rules.

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. 

Naming Variables 

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.

Leave a Reply

Your email address will not be published. Required fields are marked *