alt.hn

1/22/2026 at 11:03:24 PM

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

by siddhibansal9

1/23/2026 at 12:36:33 PM

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.

by sloped

1/23/2026 at 7:46:22 PM

This is why I hate the common pushback against "TODO:" comments. They're an extremely fast way to leave a trail of what alternative path would have been taken had there been more time. They're part of the code, so they don't get caught up in a "backlog grooming" the way a Jira ticket will, and don't break flow the way switching to Jira will.

by SAI_Peregrinus

1/23/2026 at 4:06:10 PM

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.

by birthdaywizard

1/23/2026 at 1:55:02 PM

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 .

by FrostViper8

1/23/2026 at 3:44:27 PM

In the corporate environments I've worked in it is often company policy that all commits to source code control should have messages that start with reference codes to the coresponding ticket in the issue tracker (often jira). This how I look up the whys and wherefores of code changes.

by nuc1e0n

1/23/2026 at 9:31:28 PM

A lot of places just don't do this. Unless there is a threat of a written warning some devs will do the bare minimum. I currently work with a guy that sometimes doesn't even run the code he checks in, I doubt he really knows how to code and everything is basically AI, management won't do anything and it the only remote job I could get. Another guy I work with won't do basic CSS fixes to things that are broken, so I cleaned up the login page for the site he is responsible for.

by FrostViper8

1/23/2026 at 10:48:30 PM

By whose judgement is the css you speak of 'broken'? Just making random code changes without a corresponding ticket is a recipe for troubles down the line. If you must do unprioritised work at the bare minimum create a issue tracker ticket to provide more information than can fit in a commit message. Something like selenium is good to automate acceptance testing (with screenshotting) cross browser as well.

by nuc1e0n

1/24/2026 at 1:47:05 PM

> By whose judgement is the css you speak of 'broken'? Just making random code changes without a corresponding ticket is a recipe for troubles down the line. I

Obvious display issues in a mobile app on the login which is the first thing you see. Like the login not being on the page, things being misaligned (by quite a lot). Fixed in like literally 2 minutes.

This is basically due to laziness.

> If you must do unprioritised work at the bare minimum create a issue tracker ticket to provide more information than can fit in a commit message.

I create tickets for each commit I do. So people know why I have done things. These people don't do anything of the sort.

> Something like selenium is good to automate acceptance testing (with screenshotting) cross browser as well.

I can't even get these guys to write basic unit tests for React components.

There are two different worlds. There is the world where things are done more or less properly and there is the rest of us. I've heard of some places that don't even use source control, CI builds or anything that may have been novel 25 years ago.

by FrostViper8

1/23/2026 at 8:23:06 AM

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

by pella

1/23/2026 at 9:58:55 AM

The easiest is to add short info in comments, and longer info in some sort of document and reference the doc in comments.

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.

by digikata

1/23/2026 at 7:27:46 PM

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.

by ivoryweb

1/23/2026 at 12:35:50 PM

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.

by tmsh

1/23/2026 at 11:48:47 AM

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.

by austin-cheney

1/23/2026 at 6:07:56 AM

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.

by taklimakan

1/23/2026 at 6:14:51 PM

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

by cweagans

1/23/2026 at 10:03:59 AM

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.

by krupers

1/23/2026 at 6:18:44 PM

How did you start your SWE career in 2016/2017 refactoring a COBOL application??? Sounds like a fun story!

by cweagans

1/23/2026 at 2:02:52 PM

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

by Fred27

1/23/2026 at 8:29:40 AM

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.

by alexhans

1/23/2026 at 4:44:15 PM

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.

by gcheong

1/23/2026 at 12:52:26 PM

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.

by atmosx

1/23/2026 at 9:00:15 PM

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.

by kypro

1/23/2026 at 8:52:04 AM

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.

by solaris2007

1/23/2026 at 8:16:58 AM

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.

by strogonoff

1/23/2026 at 7:53:22 PM

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.

by moomoo11

1/23/2026 at 6:45:18 PM

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.

by time4tea

1/23/2026 at 6:07:42 AM

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.

by xupybd

1/23/2026 at 10:48:25 AM

This also goes the other way too, you don’t assume the original is incorrect.

I see this a lot with developers who come in and start to criticise before understanding.

There is always a reason for why something is as it is, and it’s unlikely that the people before you were just idiots.

by mierz00

1/23/2026 at 12:34:11 PM

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.

by aristofun

1/23/2026 at 7:39:59 AM

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

by SomeUserName432

1/23/2026 at 8:46:55 AM

> Git commit will generally explain why it was done.

Sometimes, not generally. A lot of people are bad at commit messages, and commits migrated from older tools may be unusably terse because those tools didn't support multi-line commit messages well.

by palmotea

1/23/2026 at 6:35:58 AM

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.

by treadmill

1/23/2026 at 11:47:57 AM

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

by gghhjnuhbb

1/23/2026 at 7:14:39 AM

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

by Moldoteck

1/23/2026 at 7:26:54 AM

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?

by wonger_

1/23/2026 at 9:00:04 AM

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.

by hahahahhaah

1/23/2026 at 6:38:50 AM

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.

by heenrik

1/23/2026 at 7:12:10 AM

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

by abstractspoon

1/23/2026 at 12:33:00 PM

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

by Artoooooor

1/23/2026 at 10:56:11 AM

Just write comments?

by ahoka

1/23/2026 at 6:23:20 AM

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.

by bni

1/23/2026 at 1:51:54 PM

[dead]

by AnnKey