During my recent internship, I found myself working on the company's human resource management system. They trusted me enough to give me access to the whole project and even allowed me to make changes directly to the live system. One seemingly simple task, however, turned into a valuable lesson about the unintended consequences of software changes, a lesson perfectly encapsulated by Hyrum's Law.
In this article, I'll share with you my experience and how I came to understand Hyrum's Law while working on this HR system.
The Problem
One of my tasks involved the section responsible for handling leave and time-off requests. The system had a specific behavior: when an employee applied for leave while there was already a pending request, it displayed an error message to the user, saying there was a pending leave request. Simultaneously, the system sent an error code and a message to the admin dashboard, informing them of the pending request and prompting them to accept or reject it.
As I started refactoring the code, I realized that the system was in a bit of a mess. It was outdated, and the prevailing mindset was "if it works, don't touch it." This mindset, I soon discovered, was not always correct, and I will write an article about it. Anyway, During the refactoring, I made a seemingly small change to the admin's notification message.
The original message was vague, merely indicating a pending leave request without mentioning the employee's name or the request date. In an attempt to make it clearer and more professional, I added these details to the message. Little did I know, this small change would lead to significant issues.
Every Change Breaks Someone's Workflow
It turned out that one of the admins responsible for managing leave requests rarely logged into the system. Instead, he had written a code that sent him an email notification whenever a leave request was pending. The catch was that he relied on the specific text in the message, not the error code. So, when I changed the message text, he stopped receiving emails, and consequently, he had no idea about pending requests.
Fixing the Problem
Around two weeks after my change, the admin finally noticed the issue and reported it to my supervisor. Fortunately, I had been diligently maintaining a changelog file for every modification I made. With the help of this changelog file, my supervisor quickly identified the problem and updated the admin's code to match the new message format. Finally, everything started working smoothly again.
Hyrum's Law in Action
This experience led me to explore how others manage to work on complex systems without inadvertently causing disruptions. That's when I stumbled upon Hyrum's Law, which perfectly described what I had gone through.
The law says that:
With a sufficient number of users of an API, it does not matter what you promise in the contract: all observable behaviours of your system will be depended on by somebody.
In simple terms, Hyrum's Law states that when a sufficient number of users rely on an aspect of your system, regardless of what your official documentation or promises say, all observable behaviors of your system will become essential to someone.
Understanding My Situation Through Hyrum's Law
Hyrum's Law helped me make sense of what happened during my internship. Here's how it worked in my situation:
The admin had, without formal documentation, established a dependency on the message text. He had come to expect the message in a specific format, and my modification broke that unwritten contract. This was the essence of Hyrum's Law in action: the observable behavior of the system, regardless of official documentation, became critical to someone's workflow.
From my experience, I learned that you should be very careful when you make changes that means you should understand how things are connected and communicate your changes to others.
Conclusion and Advice
My internship and this exact experience taught me some important lessons, and I want to share them with you:
Write Down What You Change: Keep a list of all the things you change in a system. It can help you fix problems later, like it did for me.
Respect What's Already There: Remember that people might be using things you didn't even know were important. Be careful when you change stuff.
Talk to Your Team: Don't keep your changes a secret. Talk to your team and let them know what you're doing. They might have good ideas or warn you about problems.
Test Before You Make It Official: Try out your changes in a safe place first. That way, you can see if they cause any problems.
Balance New and Old: It's good to make things better, but don't break what's already working. Find a balance between making new stuff and keeping the old stuff working.
Hyrum's Law reminds us that even small changes can have big consequences. So, be careful and think about how your changes will affect everything around them. This way, you can make sure everything keeps working smoothly.
That's it for today! 😊 I hope you found this article helpful and gained some useful insights. If you have questions or if you've faced similar challenges, don't hesitate to share your thoughts in the comments below. I'm excited to read your comments and eager to hear any suggestions you might have for making this article even better. Happy coding!
Top comments (2)
Great post
Thanks a lot Ben for your kind words and I really appreciate you taking the time to read my post. 😊 I hope you'll keep enjoying my future articles too.