Usually the main problem with code is that it can be hard to understand. Most of the time it’s hard to grasp what the code does because we don’t have enough information readily available. In other cases, the problem is that the code lies to us. It lies because it’s giving us information that simply isn’t true.

How code lies

People don’t usually set out to write code that is misleading. This usually happens because of small mistakes that add up over time. Have you ever seen one of the following:

Comments that don’t correctly describe what the code actually does

The comments were probably correct at some point but as the code changed, no one bothered to update them.

Functions that do more (or less) things than you would expect

The function initially only did what it said, but as a new feature was quickly developed, the extra business logic was never moved to a separate function.

Variables that don’t use the data structure their name implies

The first version of the code used a list to store the values, so of course the name ValueList was chosen. After some optimizations, the values are now stored in a hash table, but the name couldn’t be modified because changing it would cause other code to fail.

How to prevent this

As you may have guessed by now, the seemingly simple, even trivial task of deciding the names you are going to use, is far more important than it may seem. Take the time to really think about the names you will use. Make sure that they don’t imply things that aren’t true. When you change your code, check your comments (more on comments in future posts) and see if any of the names you were using have to be updated. Also try not to reveal implementation details in case they will change in the future.