DEV Community

Cover image for Why can't we define "readable code"?
Winston Puckett
Winston Puckett

Posted on • Updated on

Why can't we define "readable code"?

I did some advanced writing classes. I learned that when you start out writing, there are rules. Then as you progress, you learn how to break those rules effectively. Sometimes you want to use "bad grammar" because it gets your point across more clearly.

The same thing happens in music theory; you learn the scales, the notes not to play, then you spend the rest of your time learning how to make "breaking the rules" sound good.

Programming doesn't have anything like that. And I'm fed up with it. We all know that programmers spend way more time reading code than writing it, yet there are no universally agreed upon rules for what good code "grammar" looks like.

You may be thinking, "what about self documenting code?" And yes, there are books on the subject of code smells, clean code, solid code, functional code, self documenting code, etc, but none of these are universally agreed on. If I go into a code review tomorrow and say, "why doesn't your code follow the Liskov substitution principle?" My coworkers wouldn't remember what that is. Then the next day when I ask, "why did you choose to mutate the variable instead of declaring a new one?" They will respond with a simple, "because that was the best thing for this situation."

Arguing for code readability is like trying to cut a rope in half with a hammer. You keep pounding on it but nothing changes. Nothing is concrete enough to enable a team to agree "this code is better than that code." The way teams normally solve this is by having the team lead set the standards and then everyone else just has to follow along. But that's not the right answer.

Please don't misunderstand me. I don't want everyone to be forced into a box. I want a universally agreed upon standard for writing code. Then when the stanard doesn't fit the situation, we can "use the notes outside the scale." The problem is that programming has no musical scales.

We need good grammar in our code. It would reduce debugging time, onboarding time, and increase velocity. If every other artistic pursuit and science can do it, software must have keys to readability. We just don't understand or can't agree on what they are.

Top comments (0)