Imagine you rent a vacation house with some friends. You show up, are given the keys, and step into the house for the first time. It’s dark, so you need to turn the lights on. You are met with a bank of light switches with no labels.

Dear guests: good luck with light switch roulette!

With no alternative to trial and error, you start flipping switches one after the other. First switch, nothing happens. Second switch, nothing happens. Third switch, an outside light turns on. OK, cool, at least we know the power is on. Fourth switch, you hear a garbage disposal turn on. you quickly flip it back off. You are now having some serious doubts about the sanity of the electrician that wired the place. You decide it is wise to abandon the trial and error approach. Using your phone as a flashlight, you look around for a sign or note or anything explaining what these switches do. Nothing.

Now imaging trying to implement a new feature on an existing codebase and coming across something like this:

    boolean flg1;
    boolean flg2;
    boolean flg3;
    boolean flg4;
    boolean flg5;
    boolean flg6;
    boolean flg7;
    boolean flg8;
    
    // bunch of code that uses the above flags

Like with the mysterious bank of switches, you are frustrated and unsure of how to proceed. Obviously, this “design” worked for for whoever wrote it, but they failed to take into account the needs and difficulties of others.

The code is the interface through which other devs1 will interface with the system. They will read it to understand how the system is intended to work. They will modify it to change the behavior of the system. If it’s poorly designed, both of these things will be hard and maybe impossible.

When I’m writing code, I ask myself the following:

  • Will an unfamiliar dev be able to build a useful conceptual model by looking at this code?
  • Are they going to be fooled into thinking the code works one way when it really works another?
  • Will they be able to modify the code and feel confident that the system will behave as intended?

1 This includes future versions of whoever wrote it, since you own work drifts from memory over time. This is the simplest counter-argument to “Well, its going to be someone else’s problem, why should I bother” that I sometimes hear from inexperienced devs.