Curious how teams actually handle this in practice.
When you’re modifying existing code and need to understand why a decision was made:
Where do you look first?
How often do you fail to find a clear answer?
What do you do when the original author is gone?
I’ve been running into this more often lately --digging through PRs, Slack threads, and half-written docs just to piece together context, and I’m wondering how common this really is across teams.
Commit logs, slack/email/etc, documentation silos, or issue trackers are your best bet, other than actually being able to talk to the author(s) of the code.
But in general, the decision was made because in the time the developer had to implement the feature or fix, this was the best solution they could come up with. Hopefully if there were clear tradeoffs, there is some comment as to what they might have done with more time. Likely though they were rushed, told their team they wanted to go back and fix this, and then were ushered into a new project the second this one stabilized.
I think gghhjnuhbb has the best alternative to finding actual documentation and that is sitting and putting yourself in their headspace. That can sometimes lead to insights you might have missed.
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.
Most of the time I don't know why something was done a particular way .
- https://github.com/peter-evans/lightweight-architecture-deci...
- https://adr.github.io/
- https://www.thoughtworks.com/radar/techniques/lightweight-ar...
Lightweight ADRs are a good recommendation. I've put similar practices into place with teams I've worked with. Though I prefer to use the term "Technical Memo", of which some contain Architectural Decisions. Retroactive documentation is a little misaligned with the term ADR, in that it isn't really making any sort of decision. I've found the term ADR sometimes makes some team members hesitant to record the information because of that kind of misalignment.
As for retroactively discovering why, code archeology skills in the form of git blame and log, and general search skills are very helpful.
Then the answer is just one prompt away… (I wish our team was more committed to 2 - will push for it more in the future). Having acceptance criteria in stories linked at the start of each sprint is so important though I think for alignment of work.
In some cases there are many options and great talent is readily working on the problem for the given organization. Its nice to have options, but this is an exceedingly rare scenario. For example there are tons of options available today, but from reading HN job posts it looks like the answer is still a CRUD app that does some SAAS solution with React, AI, and Python. I could guess that and be right more than 60% of the time, which is extraordinary considering these businesses have thousands of technology combinations and unlimited ideas to pick from. Its all about the talent available, but when I say talent I just mean people because when you are that restricted it isn't very talented.
To actually answer your question, do a git blame, check the commit messages and anything linked in commit messages. Do some search in the company’s internal knowledge base, architecture documents, specs, whatever you have available. Even if you don’t find a direct answer, understanding some more context might eventually lead to one.
If you have no documentation at all anywhere, then you have to analyze the code yourself. It’s part of your job. When you’re done be sure to document your findings.