DISCLAIMER

I do not claim to be an experienced developer, but I've learned enough over the past few months to save myself a lot of unnecessary anxiety. That's why I decided to write this article.

I must also admit: you can't directly learn this skill. Being comfortable with the unknown is something you pick up gradually, through repeated exposure. Time is your teacher here.

Everything I write reflects my personal beliefs and experiences. Nothing here is a strict 'law', think of it as a guideline that may or may not help. Take it with a grain of salt and adapt it to your own unique experiences.

The Unknown

Working on a new codebase is always challenging no matter who you are, even the 1000x experienced developer feel uneasy when they approach a new codebase or a problem that they are not familiar with.

It is simply human nature, Our brains are wired to fear the unknown because uncertainty feels like a threat. That's why we resort to instinctively seek familiarity and avoid the uncertain and the unknown. And the truth is: fighting it is a complete waste of time.

Surprisingly, that 'feeling' is very common, more than you think. However, the reaction to those feelings do differ from person to person. The 'reaction' is the ultimate indicator that sets apart the experienced from the inexperienced.

As the saying goes:

We cannot control the wind, but we can adjust our sails.

Experienced developers understand, just like adjusting the sails to the wind, that they can't control everything and that their knowledge is always incomplete. And that my friend, is the most powerful realization any person might have. Being comfortable with what you do not know helps you to focus on how to respond and adapt to any situation.

I know, this was a heavy introduction to this blog post, but to understand what I'm about to say next requires you to understand basic human psychology. Which is why I decided to start this way.

So, let us get into the part that everyone came for when they read the title of this article.

How do I approach a codebase and do something that I'm not familiar with?

Understand the Tech Stack

Sounds like a simple advise, yet a lot do not follow it despite knowing this.

This might be one of the most important part that you need to do. Do not dive into the project without first understand what is being used to build this specific part of the system.

Here is a general checklist:

• Being familiar with the syntax of the programming language.
• the tools that are being used.
• the design patterns, and the overall conventions of the company is also extremely important.

most importantly: Take your time when you first start working on a codebase you are not familiar with! Though, I must warn you to not go deep into every little thing in the project. A basic general view is a good starting point.

As an example one of the projects that I worked with in my job was an Angular application, I dived right into it without first understanding how this project worked (and as you would expect, I had a massive headache because I couldn't understand a thing)

I decided to start at the app level, I started to look at how the project is built, I then opened the app on the browser and started playing around with it, seen some stuff and made some hypothesis on how that part worked and then actually dived into the code and then started understanding all parts of it.

One trick I also would like to suggest is to go through the commit history, in my job we used GitExtensions which is a Git App that allows you to view git history and perform operations in a UI. it had a search feature and sometimes I would enter the name of the feature (or the file) and I would get some details that else I wouldn't have known by just looking at the code.

Mentorship

Having a mentor that knows the ins and outs of the system is extremely important. Typically, they are your teammates, your team lead, or even one of the managers. There are other cases such as people who transferred to other teams which they might still hold some knowledge about the system you are working on. My suggestion is always ask! you never know who might help you unless you ask

Also, please keep asking as many questions as you can! (preferably, do your own research first before asking to not annoy them, haha!)

Feeling Like A Fraud

One common feeling I had while bombarding my team lead with questions is that I felt like I fraud. this feeling that I'm not competent enough to 'just figure things out' made me ashamed of myself.

But do not worry!

If you are not already aware of it, it is actually called Imposter Syndrome. A recent meta-analysis study showed that 62% of developers actually suffer from imposter syndrome. it is actually completely normal to feel this way.

Minimal Change Principle

Now you got a bit of understanding of what you should do and what you might experience a long the way, it is time to talk about the crux of this article.

Minimal Change Principle is an informal principle that I named, and actually quite common approach that a lot of software development best practices recommends.

The principle is simple, do the least amount of changes to achieve your goal. Whether it is to add a new feature or to fix a bug. The point of this is to gain understanding about the thing you are trying to achieve, do it simple first and once you understand what you are changing and how to affects the rest of the components that it is dependent on, you begin actually working on the problem you are trying to solve.

Is it really easy to do? probably not. Is it fast? also probably not. is it effective once you achieve the simplest change? YES! The effects are incremental, meaning that once you gain the simplest understanding your knowledge would explode as you are now beginning to get comfortable with the problem space. You will be frustrated, you will probably quit 100s of times, but once you get your first win over the problem you are trying to solve you will move faster.

Benefits & Limitations

The Minimal Change Principle is a powerful approach, and you should consider following it whenever possible. However, like any principle, it has exceptions.

It works well when you are:

• Adding a new feature.
• Fixing an existing bug.
• Understanding a part of the system you’re unfamiliar with.

But it has some limitations:

• Its effectiveness depends on how well you prepare by doing initial research on what you are trying to change.
• It may not be suitable during the initial stages of refactoring, when structural changes are necessary.
• Eventually, you may encounter situations that require you to change your strategy entirely.

The next section shows an experience that I went through that would put the Minimal Change Principle to the test (and shows it limitations)

A Real-Life Example

This example is a real experience that I had, but I'm intentionally obscuring a few details.

When I was tasked with refactoring the company's payment gateway, I felt exactly what I described earlier: a mix of unease, confusion, and a familiar hint of imposter syndrome.

The requirements sounded straightforward on paper:

• extract the common logic.
• refactor all payment status (success, decline, etc..) to a central service.
• remove old & unnecessary code.

Then I opened the codebase...

Codebase Horror

At first glance, it was intimidating. It had files that reach 1,000+ lines of code, which immediately sent me into a panic mode. the only thought running through my mind was "am I going to refactor all of this???"

My first instinct was the typical reaction: fix everything at once.

Instead I calmed down, took a deep breath, and forced myself to look closer at the code.

That's when I started noticing a repeating pattern:

function controller_subscription_that_does_something() {
   return; // Team Member Note: This function is no longer needed in the new subscription system

   ... // logic
}

function some_utility_function() {
   return null; // Team Member Note: This function is no longer needed in the new subscription system

   ... // logic
}

that pattern spanned over multiple files, so I brought it up with my team lead, and he agreed that I should start the refactoring by removing these dead controllers. that became my starting point, I removed over 7 controllers and 5 utility functions and it reduced some files from 1k+ lines of code to just 200-400. I felt relieved, but I reminded myself that this is still the start and there is much more work to be done.

The Brick Wall

As you would expect, I hit a wall. The system was complex, full of intertwined controllers, services, and edge cases lurking in the shadows. My brain basically exploded the moment I tried to understand everything at once.

So, I asked my team lead for an advise on how to approach this. This is where a Mentor really mattered, he started by explaining that I should probably zoom out and look at the basics:

• see how payments are being created
• what api routes are being called
• and how they reacting to different payment states.

And that’s when Understand Your Tech Stack finally clicked. When I took a step back and saw how the payments work at a higher level, things became less terrifying. It felt like I was making progress, and it lead me to discover that some controllers were not in their correct file! I reported back to my team lead and he agreed with my findings.

From there, I kept making these small, incremental, and safe changes. This became my safety net and over time, it dramatically improved the readability, and increased my confidence in this unfamiliar system.

House of Cards

Even after all that clean up, there were many edge cases:

• missing payment details.
• users being redirected incorrectly.
• payment failing but subscription activating.
• payment refusing to work in apple devices (for some reason).

I started to get overwhelmed, because every time I fixed a problem, 10 other popped out of the ground. the code felt like a house of cards: whatever I touched it, something collapsed.

My team lead reminded me: "do the simplest thing you can"

and that's exactly what I did, I started isolating small problems, understand their context, and fix them carefully. some problems were easy once I understood them, other problems required me to have a meeting with the service provides to resolve.

After lots of testing and 3 weeks of grinding, and roughly 70 Gazillion mg of coffee, the system finally stabilized.

Extending the System

Once the system stabilized combined with my increased familiarity with the codebase, I can now safely extend it

Some things I ended up doing (but not limited to):

• Integrating the new payment component.
• Make the current recurring subscription system use the existing success process.
• Adding new payment methods, with proper session management and webhook handling.
• Increased security measurement with zero-trust checks

Of course, I didn't attempt all of this at once. I built each change on the understanding gained from previous fixes and iterations, carefully observing how each part interacted with the rest of the system. One thing became clear: having someone to ask questions was invaluable. I asked when needed, studied the commit history to understand past solutions, and made an effort to avoid assumptions (something I was very much guilty of).

Epilogue

What started as a daunting task became a invaluable lesson. Those minimal, careful changes were my safety net, they let me explore the system, fix bugs, and eventually add new features to the company's most critical and sensitive system.

And here is the truth: things did not become easy all of the sudden, but they became manageable. You still feel the tension and the uncertainty when working with the unknown, but you are no longer ruled by it, it no longer controls your decisions, and you start to gain enough trust and confidence in your process to keep moving forward even if the path is still not clear.

The Minimal Change Principle is less about efficiency and more about survival. It gives you a way to chip away at the unknown without drowning in it. Every tiny, controlled change teaches you something: a pattern, a dependency, a quirk in the system. Those lessons stack slowly, but they do stack.

One day you’ll notice that the same codebase that once made you anxious now feels like something you can navigate it, not because it became simpler, but because you learned how to handle the complexity without letting it control you.

I hope you enjoyed reading this article,