Well-Commented if Statements Make Software Robust

January 8, 2022

I bought my first house from my dad. It was just after the 2008 financial crash. I found a bank-owned little house that cost next to nothing, not far from where I grew up. My dad bought it, we fixed it up, and I bought it from him. I remember I was scrambling to get it done, so I could get that First Time Homebuyer's Credit.

As soon as I got the wheels turning on the mortgage, I was told that I wasn't eligible for that credit because I was buying it from a family member (it didn't help that we had the same first and last name). I was pretty pissed when I first heard that, but I'm a logical person. I understood why that rule existed. I did grow up in Crook Cook County after all, so I've always had a front row seat to shady dealings.

People buying houses from family members just to get that credit was a bug. An over-simplified check for this in a language like Go might look something like this:

func isEligibleForFTHBCredit(buyer, seller) bool {
    // Buyer is ineligible for credit if related to seller:
    if buyer.LastName == seller.LastName {
        return false

    return true

Obviously, comparing the last name of the buyer and seller isn't an exhaustive solution. What if John Murphy was buying a house from Ashley Murphy and there was no relation? The bank would still need to verify this, but that isn't really the point. The point is that adding exhaustive and explicit checks to any process prevents bugs. The people reviewing those checks greatly benefit from having the explanation right in front of them.

Let's take this analogy a step further. Have you ever had to get a mortgage? I've been on the buying and selling end of real estate transactions a few times in the last decade. What never ceases to amaze me is the profound difference in paperwork between selling and buying. After all, when you're selling, you're just signing over ownership and collecting a check (hopefully), so after 10 forms and 15 minutes, you're done. When you're the one getting the mortgage, the bank needs to know you're good for the money, so you better strap in.

I remember that somewhere around form number ninety-three, the lawyer could have said this one gives the bank your firstborn child, and I would have signed the damn thing. It may seem excessive, but each one of those forms is there for a reason. Each one tells a story. Each one is an if statement added to a function to ensure the bank isn't taking on unnecessary risk.

You may be thinking: those are just business rules driven by requirements, which are present in most software. That's fair. So, let's scrap the mortgage analogy and switch to actual code. The Kubernetes persistent volume controller uses what they refer to as the "space shuttle style" in the comments. Here's a little excerpt from the introductory comment block if you don't feel like clicking through:

// This controller is intentionally written in a very verbose style. You will
// notice:
// 1. Every 'if' statement has a matching 'else' (exception: simple error
//    checks for a client API call)
// 2. Things that may seem obvious are commented explicitly

The Kubernetes code only partially demonstrates the point I'm trying to make in this post, so I'll give you an even better example. I remember seeing some code in the Chromium (or maybe Firefox?) repo that checked for specific URLs and made accommodations due to some weirdness in the JavaScript on the site. I wasn't able to chase down that link, but I'm pretty sure I came across it on the orange site. Think about that for a second and let it sink in. A very large company with a very large user base codified the behavior if you're on https://www.thisisafakewebsite.com, don't do X, which you do for every other website, do Y instead.

I think there was only about 10 or 15 URLs with if statements in that file (don't quote me on that number). Whoever built those sites did some weirdness that required low-level changes. But you know what? If you open those websites in Chrome (or Firefox?), it behaves as expected. No weirdness. Software that solves a problem, no matter how seemingly trivial that problem may be, will always need to accommodate for edge cases and anomalies.


Is there an elegant abstraction out there that can solve the Chromium issue better than an if statement with some comments? I'm sure there is, but now we're talking about sacrificing clarity. I don't want to have to slog my way through some elaborate rule-engine code cooked up by someone who thought that URL weirdness list was going to grow exponentially.

Just make a file called edge-cases.js with a bunch of if statements and comments. I strive for this clarity and simplicity because I don't have the luxury of being clever. Make the code dumb enough for the dumbest person to understand. That's me, by the way, I'm the dumbest person.

Sometimes it's fine for code to smell a little. You can loosen a nut with a pair of pliers instead of a wrench, or remove the paint off of something with a flat-head screwdriver instead of a scraper. If you only have a few nuts to loosen or a bit of paint to remove, go for it.

The more that a piece of software is used, the more weirdness bubbles to the surface in the form of bugs. Look through the code of any open source library known for its dependability, and you'll probably find if statements for wonky, uber-specific edge cases along with explanatory comments. I've always enjoyed adding those little tidbits to my code. I can have a Sherlock Holmes moment by explaining how I solved a crime fixed a bug.

I should probably clarify that I don't believe well-commented explicit checks are the only thing that make software robust. I'm also aware that flaky software can have these checks, too. There is certainly reliable software out there that is bereft of any little "gotcha" checks. I'm guessing that software only runs on one platform.

At the end of the day, the user doesn't care if the cyclomatic complexity of a function is 15. They don't care if you have a method somewhere that's 100 lines long, 40 of which are comments explaining why we need to multiply a value by -1 on Tuesdays to render a component correctly. They just want to see the dancing hamsters at https://www.thisisafakewebsite.com.

So go ahead and slap those if statements in there, your future self will thank you.