String theory
Sorry to any physicists; this isn't for you.
This is a small idea that I came up with while teaching developers about a decade ago.
When you're designing a piece of software, I've found that it helps to imagine a piece of string in your head. That string connects to other pins or nodes. For example, if we work backwards from the end state...
- Our UI renders.
- We fetch our data and pass it to our UI.
- Our API talks to a database/API/whatever.
- An action or event triggers a request.
This is simplified, but hopefully it makes sense. Between each of those steps is a piece of string with each step representing a pin or node.
In his talk Simple Made Easy, Rich Hickey introduces the term complect (as he describes it in 2011, an 'archaic' term that means to interleave, entwine, or braid) as a warning about what not to do in a system. He introduces this illustration as a visual aid:
The point being made is that, despite starting with the same four strands in a simple configuration, when we complect them, we create a far more complex, difficult to manage system.
This is where string theory comes in. By visualizing the string in your head, you can also visualize when you're starting to tangle those strings.
So, instead of a simple RPC call to an endpoint, we introduce things like state machines, ORMs, and the like. Those aren't bad things in and of themselves, but it's good to know when they're useful versus when they're an excuse to complect.
Every part we introduce into an otherwise simple flow increases the likelihood of a knot forming. Those knots first present as logical errors and later as more serious problems like inconsistent performance or system instability.
All it takes to avoid this is a bit of awareness and some string. As you build your system, consider each part in isolation and then, how that part would interact with the others. Is it likely to produce knots or is it going to keep things simple and easy to hold in your head?
The more difficult is is to do that, the more likely it is that something has been complected, either intentionally or unintentionally.