Explaining My Technical Decisions to Other Engineers

An engineer once asked me why we should store an operation before calling an external service. I answered that it made the process safer, but I couldn’t explain what “safer” meant for that operation yet. I expected mentoring to be mainly about sharing what I had learned. It also showed me how often my own decisions started as intuition. I could look at an integration and feel that part of it should be asynchronous. I could see a service becoming too coupled or recognize that a retry was unsafe. Those instincts came from experience, but “this feels wrong” wasn’t enough to help someone else make the decision. I had to admit that “safer” wasn’t an explanation and work through why.

The Question Behind the Decision

We went back through the backend workflow and examined why recording the operation first mattered. If the call timed out, we needed to know whether the request represented new work or another attempt. If the process restarted, we needed enough state to continue. If support investigated later, the operation needed an identity before the external response existed. The question made me turn a general preference into specific failure scenarios. That explanation helped the engineer. It also improved the design discussion because the team could evaluate whether those risks applied in this workflow.

We drew the sequence and considered the moment before the call, the period while the response was unknown and the work after a confirmed result. Storing the operation first gave us a record in all three situations, but it also meant we needed to handle records that were created and never sent. The more precise explanation exposed another state we had to represent. “Safer” had hidden both the benefit and the new responsibility.

Explaining the Reason Behind the Pattern

Patterns give teams a shared language, but we can also use them before understanding the problem. Instead of saying, “Use a queue here,” I tried to explain the condition: this work should continue even if the user-facing request ends, and a temporary dependency failure shouldn’t lose the operation. Once the criterion was clear, we could compare a queue with other options. The engineer learned when the pattern was useful and how to reproduce it. This made my own reasoning more disciplined. If I couldn’t describe the constraint a pattern addressed, I probably didn’t understand the recommendation as well as I thought.

The same thing happened with abstractions. I could say that a service had too many responsibilities, but the useful discussion began when I identified which changes were happening for unrelated reasons and which dependencies made the class difficult to test. Sometimes the engineer proposed a smaller separation than the one I had imagined and it solved the actual problem with less movement in the code.

I started asking engineers to explain their decision in the pull request when the context wouldn’t be obvious later. It didn’t need to be a long architecture document. A few lines about the constraint, alternatives and known limitation often prevented the next reviewer from restarting the same discussion. Writing those notes myself also showed me when I was using a pattern because it was familiar rather than because it matched the workflow.

When Their Answer Was Different

It’s tempting to guide someone toward the exact implementation already in your head. That may produce correct code quickly, but it doesn’t create much ownership. I started sharing the risks I considered important, then asking the engineer to propose a path. Sometimes the answer was different from mine and equally valid. That could be uncomfortable when I had already pictured the implementation, but it was usually a good sign. Sometimes it also exposed a concern neither of us had considered. I wasn’t trying to make another engineer think like me. I wanted them to make trade-offs deliberately and explain their reasoning clearly. That also meant allowing low-risk decisions to remain theirs. If every choice needed my approval, mentoring had become another form of control. Mentoring conversations occasionally reached the limits of what I knew. This was useful because we could investigate together instead of pretending I had the answer. We could inspect how the system actually behaved or involve someone with more context. Saying “I’m not sure” made the uncertainty clear and gave us something to verify.

I had to adjust how much context I gave depending on the situation. During a production incident, a direct instruction could be the most useful thing because the team needed to contain the problem. During normal development, taking ten more minutes to work through the reasoning gave the other engineer room to make the next decision independently. Treating every conversation like a lesson was tiring for both sides, so sometimes I simply answered the question and moved on.

The other engineer didn’t need to pretend certainty either, and we could investigate the things neither of us knew. I expected mentoring to be mostly about explaining what I had already learned. I didn’t expect it to expose how often I was relying on intuition without having the words for it. The first question about storing the operation sounded simple, but it made both of us go through the timeout, retry and recovery behavior in detail. By the end, my answer was longer than “it’s safer,” and the design was clearer too.

In later reviews, the engineer could explain why the operation was stored before the call and which states were expected. The pull request no longer depended on me to defend the design or on the code matching the first version I had pictured.