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

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.

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.

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.

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.

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

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

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

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.

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.

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.

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

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.

Just write comments?

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.

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

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