Readability Verses Intention

Consider the clarity of your code and the intentions behind it.

I often hear the phrase, “Make your code readable.” This phrase is thrown around a lot, but the more I started pairing with other engineers, I realized there’s a gap in communication with these words. The amusing thing about an arrangement of letters is that we can say the same sentence and mean very different things or say words in an almost incoherent way by the way we arrange them. Here’s an example of a sentence in the English language that shows how absurd this can get. “Buffalo buffalo Buffalo buffalo buffalo buffalo Buffalo buffalo”.

I believe that we as engineers have to start using better words to convey what we mean and intention is one word I would propose as an alternative. Merriam-Webster defines intention as “what one intends to do or bring about”, and that is exactly what our code should do. If you try to push your code to a state where any engineer can understand your intent without talking with you directly you have explicitly made your code more readable. Let’s look at the code example below.

let orientationView = app.frame.size

if orientationView.width > orientation.height {XCUITDevice.shared.orientation = .portrait}

This code is technically readable. We want to check if the width is greater than the height and then assign something as a portrait if it is. While this is a great first draft, we still don’t know what the author’s original intent was. Not only that, we have to pull our minds into a lower-level context and load the implementation details. This was a great stopping point for me to ask more questions as we paired and asked about intent. As he started to explain his intent he was able to distill it into just a few words he said “I want to put the application under test into portrait mode before I start my test”. It was a great moment to put those exact words into code. Here’s what we did to pull those concepts up to a higher level and show intent.

if landscapeOrientation(){  
  changeToPortrait()
}

Now we have done several things with this small refactor.

1. Hidden the implementation details.

2. Shown the intent of the author.

3. Created an easy-to-test function.

As you go about your day making code more readable think about how you intend your code to be interpreted. Others and your future self will thank you.

---

Additional Reading

https://testing.googleblog.com/2024/04/isbooleantoolongandcomplex.html