Soccer or Football? Multiple names for the same thing…

For those of you reading in the distant future, e.g. more than a month from now, let me set the stage.  It is July 2018 and (as an American) World Cup Soccer is in full swing.  Now if I was anyplace else in the world it would just be “The World Cup”.  However, with either name you know what I am talking about; this is what is called a “one-to-one” mapping.

In natural, e.g. spoken languages, these “one-to-one” mappings (or near mappings) are common and can often be understood through the context of the conversation.  However, in software these mappings are problematic.

A rose by any other name… may still have thorns

Multiple names come into existence for multiple reasons.

1. Multiple developers: This is the most common reason, multiple developers working in separate models/files.  They each “need” to use a variable so they create a name for the variable.
2. Units: For physical qualities, such as vehicle speed, it is common to see, VehSpeedMPH and VehSpeedKPH.  While this may seem like a good idea, e.g. the units are known, this is perhaps the most problematic duplicate as you will often see the two instance out of sync with each other.
3. Reusable functions: In this instance, the same function is used in multiple instances. In this instance, the key observation is to have meaningful generic names in the function.
4. Common usage: For a subset of cases the reuse of names should be encouraged.  This is the scoped data with common usage.  For example “cnt” can be used for a counter in multiple models/functions.

The reconciliation project

First, determine if it is worth doing.  While consistency is important, code that is fully developed and validated may not warrant the work required to update the code.  Once the decision has been made to update the code/model base the following steps should be taken.

1. Identification:  find where the same data concept is used with different names.
2. Select a common name: Use of a descriptive name is important in these cases to smooth the transition process.
3. Check for “unit” issues:  If the different names existed due to desired units, validate that the change to the common units is accounted for downstream.
4. Update documentation/test cases: (You do have those right?). Documentation and test cases will often, reference the “old” names.  Update the documentation to reflect the “new” name.
5. Validate the units: After the updates have been performed the full regression test suite should be run to validate the behavior of the models.