"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." - Martin Fowler

You’re probably wondering if this is an oxymoron because the title says “one thing”, and the quote “says another”… I hope I can convince you it’s not the case.

People talk too much

People love to talk. The problem in programming is that all the talk is meaningless.

Maybe not now or this week. But with enough time you’ll already forget about it. Not to mention everyone else who wasn’t a part of it.

This applies even to discussions in a PR. While you can commit : “fixing stuff mentioned in PR”. Imagine the nightmare to find the PR just to find that part of the discussion was made outside of it.

Sometimes while helping someone, they start telling me what it should do or what they think it is doing. I then have to use far too many words to politely say: “Shut up. Now, show me what the code is actually doing and what it should be doing.”

I’m sure you think it’s perfect, but if it was, then you wouldn’t need to call me.

For the enlightened ones, this is a “Rubber Duck Debugging” session (for the unenlightened ones, here’s the link).

Code is the source of truth

You can talk all day, but at the end of it, only what is written in the code will remain.

"Talk is cheap. Show me the code." - Linus Torvalds

Sometimes you need to be more direct and ask for the code to say what you want to talk about.

I know I have to take care to not sound so harsh. But my point is to always say less and show, in the code, what I’m thinking.

“Code that communicates its purpose is very important. I often refactor just when I’m reading some code. That way, as I gain understanding about the program, I embed that understanding into the code for later so I don’t forget what I learned.” - Martin Fowler

Again, people talk too much, but it’s, unfortunately, common that the code is a mix of mysticism and bursts of code made for the machine to understand, the famous FullStackOverflow programmers who say ”I only know it works.”

Caring about the code is caring about the people

“Clean code always looks like it was written by someone who cares” - Michael Feathers

Maybe you’ll have to work on it later, maybe someone else. But someone will read it over and over.

“Indeed, the ratio of time spent reading versus writing is well over 10 to 1. We are constantly reading old code as part of the effort to write new code. ...[Therefore,] making it easy to read makes it easier to write.” - Robert C. Martin

Instead of taking the easy way of responding to a PR comment with a comment, chat message, or in-person conversation, change the code in a way to make such discussions disappear.

Whatever is poorly or not said with words can be made up with a more expressive code.

And if it isn’t clear by now, all that time talking and trying to understand indecipherable code adds up. So no, it’s not “easier” nor “faster” to do things that way.

Notable exceptions

One exception to this is when you know what you want to do, but can’t make the code for it. Juniors usually suffer from this. In this case, words are very good. Use as many as you can to clearly explain concepts and how to do something.

Another exception is for non-technical people. If they need to understand something, use words, not too many because they probably won’t understand but try to make it clear and simple.

Time spent explaining something to someone is never a waste of time.
If you’re a junior, remember this. And if you’re the one explaining, remind them of this.

Finally, planning time is always important:

“If I am to speak ten minutes, I need a week for preparation; if fifteen minutes, three days; if half an hour, two days; if an hour, I am ready now.” - Woodrow Wilson

I’m not saying to spend a day thinking about writing a line of code. But more people would benefit from thinking a little more before they start cooking spaghetti at 150+ WPM.