Good Practices in Development: A Bet on the Future

How many times have I heard someone exclaim, “But why did they do it like that?!” when referring to the code or architecture produced by another team? And how many times have I said it myself?

This kind of remark can be made—more or less grumpily—in two scenarios:

• Either what was done does not follow “good” practices, in which case the usual reaction is to brandish a crucifix or equivalent;
• Or what was done does follow good practices, but in hindsight, the underlying need did not actually justify bringing out the heavy artillery. The typical response then is to sigh heavily, shake one’s head, and sprinkle the word “pragmatism” into the conversation that follows.

Whenever I catch myself falling into one of these two scenarios, I make an effort to metaphorically slap my own fingers to remind myself to temper—at least a little—my judgment.

 

The first question to ask is:

 

What do we mean by “good practice” in software development?

 

 

A practice is a set of conventions or ways of doing things shared by a community, such as a development team or a company.

A practice only becomes good when it has repeatedly proven its effectiveness. The question, then, is to determine against what criteria we judge its effectiveness.

 

A Good Practice Is Defined by Its Objectives and Context

 

A good practice is not absolute. It can be summarized as a well-regarded, effective approach applied at the intersection of:

• A context: technical, technological, cultural, etc. For example, principles like API-first or Event-Driven First may be foundational elements of a company’s culture.
• A need: the intended effect that a piece of code or solution is supposed to produce.
• Performance indicators that we aim to optimize: response time, throughput, readability, etc. It’s worth noting that these indicators are not always measurable—maintainability and scalability, for instance, are often among them.

All these elements are nothing more than working hypotheses. And the nature of a hypothesis is that it can be invalidated—either immediately (as is often the case with POCs, for example) or later on.

 

Adopting a Good Practice: A Projection into the Future

 

 

The time dimension is central in two ways:

• Hypotheses can change over time. For example, one might initially prioritize reliability, only to later shift focus toward optimizing response time (hello CAP theorem).
• Some KPIs explicitly refer to the future. Take extensibility, for instance: we may optimize for something that ultimately proves irrelevant. In this case, the solution might simply be decommissioned without ever needing to evolve. Another example: we might anticipate an unrealistically high number of concurrent users, far exceeding the actual demand.

The challenge here is that we cannot predict the future—we must make choices knowing that time may prove us wrong. However, we are very good at analyzing the past and observing the present. And this is precisely where presentism starts to creep in.

 

Beware of Presentism Bias

 

We may be tempted to judge a solution today based on what we know (or believe we know…) about the past and present, rather than on what was known or imagined at the time.

Every time we facepalm and curse at someone else’s code or solution, we should instead ask ourselves:

• What were the initial assumptions?
• Are those assumptions still the same today?

These simple questions help avoid the trap of presentism or hindsight bias, which involves judging past decisions through the lens of current knowledge. But then, how can we be sure we understand the assumptions originally made?

 

Avoiding Amnesia by Documenting Decisions

 

Documenting decisions generally helps. In the context of software development, one way to address this issue is by writing Architecture Decision Records (ADR). These records archive technical decisions, the context in which they were made, and the alternatives that were considered. ADRs help contextualize and understand past choices, making solution maintenance easier.

Now, if ADRs effectively meet a need (documenting past decisions), in a specific context (software development), and with a clear optimization goal (maximizing maintainability), am I not, in fact, saying that ADRs are… a good practice? 😬

 

Conclusion

 

Ultimately, deciding whether to apply a particular practice is fundamentally a bet on the future, highly dependent on the context. A bet that seems relatively safe given current assumptions and past experiences—but a bet nonetheless.