Readability and analogy to music

In music, you can often write the same note two different ways, for example, B-flat and A-sharp correspond to the same key on a piano keyboard. When you use which depends on surrounding context. A chord C/E/G/B-flat is a C dominant 7th and resolves to an F chord. The same chord written as C/E/G/A-sharp is an augmented 6th and resolves to B major. So which way the chord is written tells you something about where it’s going next.

The other day, I saw music with an augmented 6th chord written as a dominant 7th, and I found it confusing to look at a sequence of notes like A-natural, A-flat, A-natural. Given the two notes in that sequence, you usually expect the third note to be G.

So what does this have to do with code?

Readability matters.

With code, you can often get the same end result multple ways. It’s important for your code to look like what it does, so anyone reading it will be able to understand it. Since we spend at least 90% of our time reading code (the Uncle Bob figure) focusing on readability will improve productivity.

Poorly named methods are the equivalent of that A-flat that should have been written as a G-sharp: it will sound (or work) the same, but you’re making the reader work harder than they should have to.