Ask HN: How do you find the "why" behind old code decisions?

We call this "code archeology" at my company.

We're more diligent about ticket descriptions these days, but we weren't always. Obviously the best is to be able to to talk to people, followed by documentation, either explicit documentation or on the ticket itself .

After that it can be useful to look at all commits that were related to the change itself. You can often piece together why something was done from looking at how the changes happened as whole, or even which parts were rewritten as requirements changed.

Another option is to talk to people in your org closer to clients. Support or client managers can sometimes have a better idea of how features are actually used, meant to be used, or what parts are more valuable than product or engineering will, especially if they're revisiting a feature for the first time in many years.

But yeah, often you can't. You're best bet then is to make sure you really understand the feature look at it with fresh eyes. Say "Well this is how it DOES behave, how do we want it to behave from here?" Actually talking to clients can be helpful here if any of them are willing to talk to you. In enterprise software, you can probably find a client who wants to shape the direction of the feature and has some strong thoughts.

The question you're actually trying to answer is unlikely to be "why is this the way that it is" and more likely to be "if I make this change, will I break anything". So just don't worry about it: make your change, open a PR, socialize it as widely as is practical, and if nobody stops you, merge it and move on. In many cases, the original "why" doesn't matter anymore. If it does, having a concrete change to look at and critique helps move the discussion along (and prevents getting trapped in hypotheticals - they can see exactly what you're trying to do if they have a PR in front of them).

Its what commit messages are for!

The diff tells the 'what' - no point in writing 'added method bob()'

The message tells the why.

You can bet that over time, the jiras, the issues and the confluence, slack, o365, will all have been deleted, "upgraded" or whatever, and all you have is what's in the repo.

Using in-repo ADR, and in-repo 'what's missing, what's next' files are also useful, because they co-evolve with the code.

This is why I hate the common pushback against "TODO:" comments. They're an extremely fast way to leave a trail of what alternative path would have been taken had there been more time. They're part of the code, so they don't get caught up in a "backlog grooming" the way a Jira ticket will, and don't break flow the way switching to Jira will.

Really depends on your engineering processes, but this is why you want to enforce good processes.

- Every change beyond the most insignificant package bump should be ticketed, and specifically tickets should document the business why.

- Every PR should include a high-level description of the change, and should document any technical whys. It should also link to the ticket.

- Code comments should be used where appropriate to document code-level whys and hows.

- For significant architectural changes ADRs should written up to document why the architectural change was made.

Failure for your team to do this results in the problem you're experiencing now.