“What does this thing do?”

There are many principles and rules out there that offer guidance about good code design. I am generally skeptical about dogmas. Nevertheless, sometimes when I am deep in the trenches I do find it useful to have a rule of thumb to apply to quickly assess whether I’m on the right track.

Such a rule of thumb is also useful to help juniors, especially since I have stopped recommending go-to literature such as Clean Code as the advice there ranges from very good to somewhat dubious.

The question I found most helpful for guiding my work is “What does this thing do?”

The way I apply this question is simple: While writing a class, a function, a module, or a script I try to find a sentence that provides a concise answer. This answer should be understandable by someone external to the project but with a reasonable understanding of the domain. If a concise description of what a unit of code does without a lot of ifs and buts is challenging to formulate, something is not quite right.

Think about it that way: Why do we care about code quality in the first place? I would argue that it is about the ability to make changes later on, quickly find problems, and onboard newcomers more easily.

Each of these activities hinges on the ability to quickly understand what a piece of code is supposed to do. The next person will ask exactly this question while trying to reproduce a critical bug that brought down production a couple of years later.

The approach is similar to the “single responsibility principle”, the “S” in SOLID. You might even say that my definition is less precise. Then again, defining responsibility also leaves some room for interpretation.

Furthermore, I do not necessarily agree with all of the other SOLID principles. At the very least they are very closely tied to object-oriented designs. We now have access to an arsenal of other design paradigms like functional or reactive programming which all come with their own sets of best practices.

“What does this thing do?” on the other hand has served me well across paradigms.

In conclusion, while this may appear somewhat trivial, some might find this a valuable exercise: Next time when you’re deep in the zone try asking “what does this thing do?” and maybe that will help identify and avoid some overly complex patterns.