When Code Lies

I don't appreciate being lied to, and I bet you don't either. It's an awful feeling when a lie is discovered. In my life, I've found that some people are terrible liars—my kids are in that camp, for instance. I can tell right away when one of them is trying to bend the truth on Vanessa and me. But there are some people I've met who seem to have become professional liars. I never quite know if they are telling me the truth or not. 

When I first started programming, I thought writing code was merely giving the computer a series of commands to follow. Over time, I've come to realize that programming is actually a conversation—it's a conversation that will happen between you and someone in the future. It's a written conversation instead of spoken, asynchronous instead of real-time, but the same rules apply. What you write communicates truths or lies to a future someone—this may be a teammate or even a future version of yourself. 

Bob Martin, widely known in programming circles as Uncle Bob, first introduced this concept to me. Growing up in the church, this idea of your code speaking truth or lies really caught my attention. I knew from Sunday school that one of the Ten Commandments had to do with lying. I also remembered that Jesus called himself The Truth and said that it would set you free. So, this idea of telling the truth with code felt important. It's the kind of thing I imagine Jesus would have talked about with friends—if he had been a programmer instead of a carpenter.

If code can lie, then what exactly does that look like? Let's look at three common examples.

Wrong Names

Wrong names happen when people are in a hurry. They need to bang out a feature and can't afford to pause to consider a name truly. It's the variable named ball, even though the design changed to a puck. It’s the factory class that doesn't actually return a new object. It's choosing not to adopt the terminology the designers use because it would require renaming many systems. It's an attitude that says, "You know what I mean." "It's good enough." It's a damaging mindset that can become contagious the longer a project takes to complete.

Incomplete Names

Unlike a wrong name—an incomplete name is technically correct, but it doesn't tell you everything. It's an omission of truth that I tend to see most often with method names. Let's say you have a SpawnPlayer method, which places a player in the world. However, upon further inspection of the function, you discover multiple code lines concerning the player's creation and configuration before placing them in the world. Sure, the code spawns the player into the world, but it's doing more than its name suggests. This type of problem tends to happen for two reasons. One, you're trying to do too much with a method. Or two, convenience—as in some code needed to be added, and this method happened to be the most convenient spot to stick it. 

The big problem with these half-truths is that they tend to create subtle gameplay bugs. Take our SpawnPlayer method, for example. A teammate sees that you made that method, and they use it without carefully reading all the details. They intended to place the player in level 2. However, our code creates a whole new player before placing them in the level.

Outdated Comments

Comments tend to be liars. It's not their fault in some ways; it's more of a byproduct of their design. Let me explain. Comments are pieces of code that don't execute. All the other code in your program runs, which means it gets the most attention. Make a mistake in code that runs, and your game might not compile, or an error might pop up when you play. Code that runs takes center stage spotlight, while comments tend to lurk in the shadows. Sure, you know they are there, but once you've read the comments, your eyes tend to skip over them. 

Throughout development, your production code will continue to evolve and change. Yet, your comments will remain the same. One day, a new person will join the team, and they will encounter your comments for the first time. By this time, the comments are badly out of date. There are comments referencing features that got cut six months ago—notes detailing workarounds to bugs that were fixed two versions back. There is even a ghost comment that doesn't seem to connect to the code around it. What happened to the bit of code that this comment was attached to? Did the code move to a different place in the file? Maybe it was refactored into another file? Nobody knows… it's a relic from the past.