Software Design Heuristics

The cruelest part of being trapped in the fifth-year plateau is that you are now competent enough as a software engineer that you know what garbage looks like and you know what good looks like, but you can’t always get there. A lot of the code you write is amazing, but some of it (most of it) is still absolute garbage. You cruise along with absolutely zero sense of pride in your work while the bosses can’t praise you enough. You’re the most important person on the team and you’re not even doing very good work.

The problem is that you can’t really explain why this code you wrote was good and this other code you wrote sucks. You just know that it’s good or not. Being able to recognize quality isn’t the same as having the words to describe what constitutes quality. There is an idea from linguistics that if you don’t have a word for something then it won’t exist as a concept in your mind.

Engineers I’ve trained previously are now off running their own teams and the most common piece of feedback I keep getting is that they teach the words and concepts and ideas that I taught them to their new team members and it changes everything. Suddenly everything clicks and because they can explain what they’re doing, they can write high quality code on purpose, consistently, every time.

The words and concepts are heuristics—loose rules or guidelines to assist decision making. Software design, at the lowest levels, is just about deciding where things go. Do I put this code in this class or that class? Is this method too long? How many functions should I break this into? You probably already do this by feel even if you don’t have the words.

Some people have bad heuristics for designing code. I once asked a developer why he split one method into two and he said that he split the method because it was bigger than the viewport on his text editor. That’s not a heuristic that’s going to help you write better code, but the one thing that guy had going for him is that he was enjoying the benefits of not having to make all of his decisions from scratch.

English Common Law legal tradition is based on heuristics. Judges strive to ensure that future cases are decided the same way that past cases were. In a way this makes their job much easier because they just look up the previous ruling. As opposed to French Statutory Law where each judge is allowed to make up any decision they want. During each case they start over from a blank slate. The end result is that under Common Law systems it is much easier for an Attorney to predict how a judge will rule on a particular question.

You have to make thousands of decisions every day. Add a few good heuristics to your practice and you will do much better work with less effort wasted on questions that we already answered before. That leaves more energy left for the novel questions—and that’s where the fun is.


Let me know what you thought of this post: david@palaverist.com.
I read every email.

Published by David Zuidema

Master Software Craftsman

Leave a comment

Your email address will not be published. Required fields are marked *