There are few hard rules I apply to software development. But this I can stand behind: Don’t be a liar.

There is never a good reason.

If your code is lying to me, I don’t know what else in your code I can trust. As trust in a project’s code slowly degrades, so does developer effectiveness and happiness. You really have no reason to lie with your code. And each lie builds on the next to create a seriously big pile of poo.

When you lie, your intention is unclear

When I see a variable named dogs but I see:

const cat = dogs[0];

I have 2 questions in my mind:

  • Should dogs be named something else?
  • Or, should we just not be storing this other cat object in here?

What are you trying to do?

When writing software, we’ve got a million things in our minds. We’re holding call stacks in our head while we’re staying focused on our goals. We’re considering the specs we’re working on implementing. We’re thinking about whether a module’s responsibilities are sane. We’ve got a lot of things going on.

And here you’re trying to give me an additional thing to keep in my head that’s ambiguous and will require me to probably git blame you and send you a message so I can ask you what you were trying to do here.

Don’t do it. Don’t be a liar.

When your comments lie, it’s time consuming for others to double check their accuracy

// get the bone
const doNextAction = () => {
  dog.lickOwnerFace();
}

When you have a comment that isn’t accurately reflecting the code its referring to, you’re essentially hiding bugs with your own words. I’m sure you’ve done this before:

  • Skim through code (probably in some huge mega-function that’s 800 lines long)
  • Look for comments to help you make sense of the mess
  • Move forward with the comment’s knowledge in your mind
  • Run into some weird bug
  • Realize it was because the comment was wrong and so your understanding of the system was incorrect
  • Fuck.

Don’t do it. Don’t be a liar.

Avoid the commenting and just write specs and tests instead. That way, at least your assumptions are being exercised in tests and everyone is reading a test’s description when it’s run rather than in a comment that may not be accurate.

I’ve been lying, how do I fix it?

Unfortunately, you probably already have some lies in your code.

Sometimes, especially in legacy systems, it can’t be helped. These old code bases haven’t been refactored to reflect new learnings or knowledge in the code. For instance, renaming data can involve database migrations that can be expensive and dangerous.

Say we’re doing something silly like calling a phone number a username:

const user = {
  username: 4158675309,
  profileName: 'jenny',
  ...
}

const contactUser = (user) => {
  sendSms({
    phoneNumber: user.username, /* 🤔🤢🤮 */
    text: "I've got to make you mine"
  })
}

You’ve got littered around your code base all these lies where you’re requesting a username but actually getting a phone number. WTF?

OK, fine. It’s a mess. Folks before you are to git blame. But we must move forward with what we have. If you’ve inherited a system with lies, you should not be persisting them.

What do we do?

We isolate the lie.

const getPhoneNumber = (user) => {
  return user.username; // this is a lie, but at least it's only here
}

const contactUser = (user) => {
  sendSms({ phoneNumber: getPhoneNumber(user), text: ... })
}

You’ll start seeing getPhoneNumber all around the code rather than the user.username lie. Yes, it’s more code, but it’s code that’s a truer representation of the world with a more accurate expression of how the system works.

Not only have you avoided lying yourself, you’re also giving the team a way out of its pile of lies. Good job at not being a liar.