Why Did The Devs Do That?

I saw the question “How do you find the “why” behind old code decisions?” on Hacker News and had to respond.

This is what I said.

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.

I had more to say, so I will say it here.

These days I spend 90% of my working time on a digital art project with over 30 years of development history. Before a single line of code was written, the creator of the project spent 20+ years thinking about it. So 50ish years of decisions are sitting on my machine right now, both development and artistic.

The code base is made up of several repos, most of which were messily transitioned from svn to git at one point. History was lost, documentation is scattered in an old svn repository, Jira, a archived Trac project, git markdown files, inaccessible Slack channels, Jabber chats, and meeting notes lost to the bitrot of time.

So how do I consider previous decisions when I am modifying code written by developers who are long since departed this codebase?

1. I look for comments in the source. I also read the code. With a decade on this project, I occasionally have flashes of insight. Usually it involves the client¹ changed their mind. (Honestly this is the answer 89% of the time on all projects. If you think there is not a client, you need to look harder).
2. I ask the client. This can be useful and sometimes leads to deeper understanding of the intention of a feature that was marked as completed in the past. For most projects this is probably only a few months, but if you are learning about a code base, the more business/human context you have the better.
3. Old emails and Issues are also good resources, if you have a way to search them. Hopefully you will get a comment thread where the developer or developers are clarifying expectations as they go. But usually all you will get is a title, maybe a reasonable description, and then a marked completed activity.
4. VCS history is very rarely super useful in figuring out why without additional context in my experience. Only on projects where VCS hygiene was extremely vigorous do commits and commit messages signal why. Usually they end up being a mix of; fixed a bug, whoops, ci commit, ci commit, etc. But git blame can at least help you when searching old emails or issues.

The truth is that even after doing all of this, there is a better chance I have to just guess at intentions. They were probably good, they may have been misguided, rushed, or not backed by as much skill as we might like. Someone asked for something, the developer delivered it, and if it’s been in the code for more than a few weeks, it probably solved a real problem.

In the end, the why something happened is not the important bit anyway. Why can help you feel good or worse about something. But today’s problem is what is important. Instead of wondering why they (and let’s be honest, you) did something 6 months ago, instead focus on what the impact of changing this decision will be. And leave a comment and write a good commit message, do better than the past.

¹ Client may be singular but can be made up of numerous individuals. Someone, maybe just you the developer, is the client.