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 HN: How do you find the "why" behind old code decisions?
11–20 of 44 posts
Re: Ask HN: How do you find the "why" behind old code decisions?
#12retroactively - 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://www.thoughtworks.com/radar/techniques/lightweight-ar...
Re: Ask HN: How do you find the "why" behind old code decisions?
#13The 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.
Re: Ask HN: How do you find the "why" behind old code decisions?
#14> 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.
> 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.
Re: Ask HN: How do you find the "why" behind old code decisions?
#15If 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.
Re: Ask HN: How do you find the "why" behind old code decisions?
#16Search 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.
Re: Ask HN: How do you find the "why" behind old code decisions?
#17retroactively - 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...
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.
Re: Ask HN: How do you find the "why" behind old code decisions?
#18This 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.
Re: Ask HN: How do you find the "why" behind old code decisions?
#19You 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.
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.
Re: Ask HN: How do you find the "why" behind old code decisions?
#20Just write comments?