A directory of brand guidelines: logosearch.link

Writing code for others to read

Dom Habersack
Dom HabersackApril 29, 2020
Write without fear. Edit without mercy.
Merge without concern. Release without waiting for Monday.

Like people-languages, programming languages have a vocabulary and grammar. In both types of languages, we can phrase what we want to say in several ways and still get the same point across. Books written with unfamiliar words are difficult to follow, if thou catch mine drift. This is what reading other people’s code feels like.

When working in teams, the most effective code we can write is one that others can read without a lot of effort. Writing more readable code starts with picking better names for variables and functions.

Domain language inevitably ends up in our work. We use abbreviations like CTA and ETA and expect everybody else to also understand them. Some people have never referred to a button as a “call to action” before. Others have to spend a lot of time with calculateETA() to learn that it returns an “estimated time of arrival”.

Through naming things by our domain knowledge, we put up a barrier of “you must be this tall to read this” in our code. We are making our colleagues’ lives difficult for no reason by trying to be terse and clever. There are no prizes for “shortest code ever”. If a name becomes more readable by adding a few letters, that’s an easy decision to make.

A good rule of thumb for naming variables and functions is:

If someone could ask “what does this mean”, it’s not a good name.

The name calculateEstimatedTimeOfArrival() seems very long, but it leaves no room for misinterpretation. Readers will definitely have an easier time figuring out what it does.

You are not writing code for yourself or the computer. You are writing code for others to read, and they might not know all those abbreviations yet. Do them a favor and use better names.

– Dom

Continue reading

The ruin of a house on an open field in front of a mountain.
#29March 25, 2020

How to write legacy code

No code starts out as unmaintainable legacy we don’t dare to change. All codebases end up there because of a lot of small decisions like these examples.

Assorted colorful miniature houses.
#69December 30, 2020

I finally understand “many small functions”

Writing many small functions instead of a few large ones is common wisdom. It took a book from the 90s for me to understand why that’s better.

A model of a space shuttle.
#80March 17, 2021

When you know too much to be helpful

Once you speak the language experts in your field use every day, it becomes harder to remember what it was like to not know what you know now.

Read all issues →