don't worry, it's probably fine

This is a write-up of a talk I recently gave at work for our tech team meeting, about readability, inspired by a session at SoCraTes UK 2023.

I’m going to show some code, take a minute or two to see if you know what they are doing.

⪾(+⊙(⊢⊚)|=⊙≡(⧻⊝)|◫)

Pretty easy. What about this one?

int solve(char[] input) {
    for (int i = 0; i < input.length; i++) {
        HashSet<Character> k = new HashSet<>();
        for (int j = 0; j < 4; j++) {
            k.add(input[i+j]);
        }
        if (k.size() == 4) {
            return i + 4;
        }
    }
    return -1;
}

Or this one?

def solve(input: str, window_length: int):
    number_of_sliding_windows = len(input)-window_length
    
    sliding_windows = [input[i:i+window_length] for i in range(number_of_sliding_windows)]

    unique_characters = [len(set(window)) for window in sliding_windows]

    first_window_all_unique = unique_characters.index(window_length)
    
    return first_window_all_unique + window_length

These pieces of code (in uiua, java, and python respectively) all do the same thing. They are solutions to Advent of Code 2022, day 6. Given an input string and a positive integer N, how far into the input string must you go before you have a window of N distinct characters?

You will probably have found that one of the three solutions is more readable to you than the other two, but a group of people may not have the same consensus.

Readability is a subjective experience formed from the interactions between the thing being read (“artifact”) and the person or group doing the reading (“audience”). To be even more specific, readability is not a property of the artifact alone.

I could strongly assert that “artifacts are not readable” but that wouldn’t be telling the whole story either. All artifacts are readable by something even if that thing is only a process compiling or executing code.

Making things more readable…

How, then, do we make things more readable? Changing readability means changing the relationship between the artifact and the audience.

The artifact can change, which is probably the most common experience people have, refactoring out unnecessary complexity or duplication.

The audience can change. If you have a codebase where one person has a lot of knowledge about the language or implementation and they leave, the artifact has become less readable. The code hasn’t changed, but the audience has.

The relationship between the artifact and the audience can change. Upskilling your team, using learning and development budget for training, or activities in your team like group refactoring sessions. One of my colleagues at my previous job ran a regular session called “Style Council” where his team talked through different solutions to the same problem.

…for whom?

You need to have a firm grip on who the audience for your artifact is in to make the most effective decisions around readability. I have been guilty of the common “Make X more readable” change on many codebases I’ve had the pleasure (or pain) of working on. The problem with this is that whenever you’re not specifying an audience, there is an implicit audience: the author of the change. “Make X more readable for me”.

Sitting down in your team, or even by yourself, and being explicit about the target audience of your artifacts makes it easier to make changes in favour of readability because you can target changes most effectively.

• Who interacts with your code?
• Who needs to understand it?
• Who are you catering for (and by extension, excluding) in your definition of readability?

The ability to be explicit about exclusion is a double-edged sword. The majority of the code I work in is public. Should our primary target audience for readability be “everyone with an internet connection”? I don’t think so, others may disagree. The team, the programme, and the wider internet are all audiences for the code I work on but in diminishing order of priority.

The other side of this is making sure that you factor in the fact that audiences change. New starters in your team or organisation are also an audience even if they don’t exist yet. Are you making readability changes that entrench the skillsets of the people already in the team, or are you making changes that lower the bar for new starters or contributors?

Leaning on standards

The great thing about knowing your audience is that you can agree on patterns and standards for readability, and once those things exist you can automate them. Imagine that you can go from one codebase to another and easily know how it works despite never contributed yourself. This is one reason why companies with large engineering disciplines often invest in “developer enablement” or centralised platform teams.

Standardising raises the bar for readability across many teams, and I’d argue essential for on-call teams. The principle of least astonishment is a great asset in incident management situations.

Wrapping up

Next time you’re thinking or discussing improvements to readability, try these things:

1. Talk about what readability means in your context
2. Establish your audience and codify it
3. Automate agreed patterns using linters, formatters, static analysis tools
4. Share with others raise the standard for everyone