The honest answer is you probably won't find it. Historical documentation is hard, it is the first "features" cut when teams are scrambling to meet a deadline. There is no malice in this, it's just something that the end user doesn't need or see so when shit hits the fan, it get skipped.

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 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.

I look through commit messages and try to link it up to a Jira ticket and piece it together. Often the original developer has left, or if they are still present doesn't remember why.

Most of the time I don't know why something was done a particular way .

retroactively - create Lightweight Architecture Decision Records (ADRs) by reconstructing key decisions from the available sources, then make it a habit to maintain them for all future changes.

- https://github.com/peter-evans/lightweight-architecture-deci...

- https://adr.github.io/

- https://www.thoughtworks.com/radar/techniques/lightweight-ar...

I’ve run into this a lot. In my experience the “why” usually isn’t in the code or the docs—it’s in the constraints that existed at the time (latency, incidents, org structure, missing tooling). What helped me was reconstructing the failure modes they were guarding against, not the feature intent. Once you see what they were afraid of breaking, the decisions make more sense—even if they’re obsolete now.

It’s a reason to push one’s teams to have conventions: (1) all commit messages have an issue number (2) all issues have acceptance criteria or link to issues that do.

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.

The answer to why is almost always because that is the limit of talent available to the organization at the time with the given technology options available. Its really that simple.

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.

It’s either documented or it’s not. When I modify code in a way that isn’t immediately obvious by looking at the code itself plus the immediate surroundings, I write a two-or three-lines code comment. It takes me ten seconds and does a big favor to my future self. I fail to understand why this isn’t standard procedure.

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.

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).

This thread makes me think of when I was refactoring a COBOL application when I just started my SWE career in 2016/2017. The original program was from 1989 and things like git blame, ticket systems etc. wasn't there. There was rudimentary version control, but that didn't go back to far, and also surprisingly there was some documentation. But the major thing that helped me answer the "why's" was that the original programmer still worked in the same department, and he actually remembered some of the choices he made. Other than that, it was a matter of remaking the same mistakes and figuring out the "why's" the hard way.

Anything that has a "why" _should_ have a comment. I know people like to structure code so that it doesn't need comments. However, nice clean well structured code can describe the _what_ without comments but never the _why_.

The fact that you have to dig through things to find it should give you good hints in what is desired for your own code. You want your WHY comments very contextual and findable.

1. Either literally as a comment in the code. Immediately findable

2. As a description in the commit (easy to find with git blame).

3. As a comment in the Code Review/Pull Request system. This works for very stable things but is more brittle than the other ones. Usually exposes the discussion among parties but the outcome of that discussion should probably be in 1. And 2.

Another benefit of keeping comments in the context of where they happen is that you'll actually remember to update them. Otherwise, they're duplication (code smell) and introduce a risk of divergence.

That's why WYSIWYG standalone word docs or similar for design or manually written wikis are so dangerous for code that lives and keeps changing. The thing that keeps teams tidy is often single sources of truth where you can generate/render other things easily.

---

Reading tests or talking to someone is possible but if you had to do that for everything you might waste a lot of time so while it can be extremely beneficial I don't consider it my thought process.

Sometimes the why is discovered when you try to change the code to what you think it should be and see it fall down in some cases you didn't anticipate or some other system is affected. It's often really hard to find out the why but either it will become clear at some point when the code is refactored or it will be irrelevant.

Through commit messages. I can’t show our repo but most of the important decision made by the two top contributors have commit messages that look like ADRs. Sometimes five paragraphs long explain what was, why and what is.

Now with AI it’s a lot easier to ask the bot to put together the reason behind this or that by sharing commit history.

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.

If you aren't on a high talent density team comprised of people you have learned you can trust, assume the worst because far too often the original author didn't know why either.

Taking to the person who did it (who wrote the code, who reviewed it, who gave the specification, who worked anywhere near at that time) is the best way to understand why it was done.

When I used to work at my previous job, it was required that we have detailed PR descriptions (we had a template) and our commit messages were meant to be concise/clear.

So in practice it was usually not too bad. Git blame on any line could point me to the PR and any associated ticket.

You just need to have some discipline among the team because there would be slackers who didn’t want to take an extra 5 min. But you know. You weed them out.

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.

You often can't. Also don't assume the original why was correct. Instead learn the problem domain so well that you can make your own judgements.

Poorly, and typically by making the same mistake enough times to document the decision. Code archeology is a bitch and a half.

https://en.wikipedia.org/wiki/Wikipedia:Chesterton's_fence

Hi level answer is always - to satisfy the product/customer requirements.

If the requirement was never documented or lost, then you can only deduce it like Sherlock Holmes.

Low level answer is always- because this is the best way current developer could come up with given the organizational context and his level of experience.

> Where do you look first?

Git commit will generally explain why it was done. The task it references may or may not explain the decision process that lead to it. Usually not.

It's rarely related to code, more often a business decision due to some obscure reason/desire which may or may not provide any actual value.

Read the BDD style acceptance tests that were written during development. This is the one chance you get to preserve that knowledge when it fresh and correct. Asking someone three years later (even the original dev) is no substitute. Oh, and you can also run the tests to ensure correctnes.

Ask the person who wrote it. If they are gone, think very hard for a few fays about the problem and the thought space they were in. If all else fails, change the code and watch what bugs percolate.

Edit: typo

Git blame if I'm lucky the commit to be documented

Do any teams keep a decision log for these sorts of scenarios? Especially when a comment is not enough, e.g. architecture or dependency choice?

Search slack. Find chesterton there.

Otherwise cross reference ticket.

Otherwise search docs.

Otherwise ask teammates.

Otherwise don't change it.

If you have to change it have a careful rollback / DR plan.

Tangential: Peter Naur has something to say about this in his "Programming as Theory Building" paper.

TL;DR: You have to reimplement the application or features to understand the "why" regarding technical decisions.

I use 'git blame' to help me find the commit and the branch, and then infer the rest

I ask on the project chat. When I am ignored I use enough expletives to stop being ignored.

Just write comments?

If it's architecture you need to time travel back to the time and the circumstances, requirements and priorities around that time. Good luck.

When it comes to code, run the unit tests.

[dead]