Tidy First?

Untangling a ball of yarn starts with noticing that you have a tangle. The sooner you realize the need to untangle, the smaller the job is (and the less important the decision between the strategies becomes). When you first begin consciously tidying, whether first or after, you’ll likely miss the transition between “cruising along making changes” and “oh no, what all have I done?” Don’t worry. You’ll get better at sequencing tidyings and changes over time.

Creating a pass-through interface is the micro-scale essence of software design. You want to make some behavior change. If the design were like thus and so, making that change would be easy(-er). So make the design like that.

Is there enough time to do your work? I’m not asking whether you have plenty of time, because of course not. I’m not asking whether there’s more to do than you have time for, because of course there is. Ask yourself, “How would we work if we had enough time?” If the answer is wildly different from what you are actually doing, then no, there is not enough time to do your work.

Your job as a software designer is to set yourself and your team up for success, now and in the future.

Since change is the dominant cost of software development and understanding code is the dominant cost of change, communicating the structure and intent of working code is one of the most valuable skills you can exercise. Comments are a form of communication, but tidying lets you explore the limits of communicating through the other elements of programming.

Let’s say you’re reading a file (we can have the debate about whether source code belongs in files some other day). You read the whole file, and you get to the end and there it is! The detail that would have helped you understand all the rest of the file.

Reorder the code in the file in the order in which a reader (remember, there are many readers for each writer) would prefer to encounter it.

You’re a reader. You just read it. So you know.

Another aspect of the puzzle of software design is figuring out what forces drive it, and what principles to use to respond to those forces. Much design advice just flat-out contradicts the available evidence. Why is it that skilled designers produce results that can’t possibly proceed from the principles they espouse? What’s really going on?

To understand any program, whether to create it or to correct it or to change it, requires understanding the piece of code immediately in front of you as well as those other pieces to which it is connected, which it depends on or affects or is affected by.

When you see a comment that says exactly what the code says, remove it.

The purpose of code is to explain to other programmers what you want the computer to do. Comments and code present different trade-offs for you as a writer and for future readers. You can explain anything you want in prose. On the other hand, there’s no mechanism to double-check the accuracy of prose as the system changes, and comments might become redundant as the code evolves.

For me, there is a whiff of sadism in programming, a heroic self-immolation on the pyre of complexity. The world is challenging enough that we can’t afford to ignore opportunities to make things easier for ourselves and others.

Most important, though, is you. Will tidying bring peace, satisfaction, and joy to your programming? Maybe some. This is important because if you are your best self, you are a better programmer. You can’t be your best self if you’re always rushing, if you’re always changing code that’s painful to change.

What makes those expensive changes expensive? It’s when changing this element requires changing those two elements, each of which requires changing other elements, and… and… and…. What “propagates” change? Coupling. So, the cost of software is approximately equal to the coupling:

In general, we should treat reversible decisions differently than irreversible decisions. There’s great value in reviewing, double-checking, triple-checking irreversible decisions. The pace should be slow and deliberate. Even if there is a great upside to the decision, there is also potentially a great downside if we get it wrong. Yes, we want the upside, but even more we want to avoid the downside.

The word “coupling” has lost its meaning over time, coming to mean any relationship between elements in a system. “This service is coupled with that service”—okay, but how? With respect to what changes? It’s not enough to know that one service invokes another; we need to know what changes to one service would require changes to the other.