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.

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.

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.

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.

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

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.

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

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.

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

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.

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

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.

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

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?

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

Just write comments?

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.

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.

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

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.