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

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.

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.

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.

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

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?