Coding is Easy; Communication is Hard

This is one of the phrases I find myself perpetually muttering because it is so patently true. I gained newfound respect for one of the titans of software development, Martin Fowler, when I rediscovered his famous quote:

“Any fool can write code that a computer can understand. Good programmers write code that humans can understand.” — Martin Fowler

There are so many things about writing code that I wish someone had told me when I was coming up through the trenches. Maybe they tried, and maybe the words were lost on my youthful arrogance or my ears had not yet been opened sufficiently by the fires of experience. Or maybe I tried too hard to emulate people with a mastery of coding skills without devoting commensurate time to emulating role models with commendable communication skills. Yet the older I get, the more I realize that coding is the easy part: communication is what’s difficult.

I am fond of stupid jokes, and this one in particular. A man is out walking and sees a beautiful horse with a sign “For Sale: $10”. He asks the seller: “Really? $10? What’s wrong with it?” The seller replies, “it’s a great horse, but he does this thing… he sits… on grapefruit. It’s a real pain to get him off of one.”

So the guy is thinking… has he ever seen a grapefruit while out on the trail or lurking around his stable? No! So he decides ten bucks is worth the risk of encountering a grapefruit, and he buys the horse, and happily takes his new steed for a ride. They trot up windy mountains and gallop through mossy woods, and this amazing horse never breaks stride! But when they ford a rocky alpine river, without warning, the horse drops his haunches and sits down, dumping the rider into the frigid water. The man is shocked and shivering, but then he remembers… grapefruit. He looks and looks, but no grapefruit! His efforts to raise the animal all fail, and eventually he has to walk dripping wet in the dark all the way back to the man who sold him the horse and bangs on his door and vehemently lodges his complaint about this stupid horse and how there was emphatically no grapefruit.

“Oh, snap, I forgot!” says the man, slapping his forehead, “He also sits on fish!”

Takeaways

In a culture oversaturated by information where we are trying to take sips out of a firehose, I will attempt to summarize some words of wisdom born out of my observations and a stupid joke.

1. Every Git commit is an opportunity to communicate your intention. What is the one thing this change does? If you can’t describe it in a single sentence, maybe you need to practice writing your words more, but maybe that commit is doing too much. We don’t want stupid commits that free associate fish and grapefruits.
2. Names matter. They communicate what something is and does. Choosing a descriptive function or variable name does more for code readability than any comments. Is it a fish or a grapefruit?
3. File structure matters. The structure communicates expectations. Are you choosing sensible directory- and file-names that accurately describe their purpose and contents? Does this directory contain fish or grapefruits?

In a nutshell, the principle of Single Responsibility Matters. Why? Because it helps communicate in a straightforward manner. We can wrap our brains around an app, module, function, horse etc. when it does one thing. Each component should solve one problem. If you cannot succinctly put into words the purpose of a particular app/module/function/horse, then you have no real clarity on what it is or how to use it. If you can’t verbalize the purpose of a thing, you will be unable to wield it effectively because you don’t really know what it is. Does it sit on fish? Or on grapefruit? Or some dumb combination that makes no sense? And how come you don’t know what kind of horse you’re selling? Get your story straight because that’s how you communicate more effectively. And when you get orientated and are communicating effectively, good code can follow.

Happy trails!