Devesh Korde
November 2, 2026
I was exploring our codebase one day.
I found this comment:
// WARNING: DO NOT MODIFY THIS SECTION
// This handles user permission edge cases from 2015.
// The logic is fragile. Changes here have broken production 3 times.
// If you need to change this, talk to Dave (he left in 2023).I thought: this is funny. Dave left three years ago. Nobody knows why this code is the way it is. But everyone is terrified to touch it.
So I started looking for more comments like this.
I found dozens. In every service. In every team.
// DO NOT TOUCH - used by legacy system
// FRAGILE - test everything if you change this
// DANGER - mutation happens here
// DO NOT REFACTOR - business logic is complexAll the same message: "I do not understand this code and I am scared of it."
I got curious. Why is this pattern universal? Why does every codebase have these untouchable files?
So I investigated.
The "DO NOT TOUCH" files fall into three categories:
Category 1: Legacy Code Nobody Understands
This code was written 5+ years ago. The original developer left. The code works. But nobody knows how. Or why. Or what would break if you changed it.
Example:
function calculateDiscount(order, user, date, region) {
if (order.type === 'bulk' && date.getDay() === 3) {
if (user.vipLevel > region.threshold) {
return order.total * 0.15;
} else if (date.getMonth() === 11) {
return order.total * 0.10;
}
}
// ... 50 more lines of nested conditions
}Why is it a minefield? Because the logic is so specific that you cannot understand the intent. You can only see the rules. And you do not know which rules are essential and which are technical debt.
Category 2: Performance Hacks
This code is ugly. But it is fast. Removing the ugliness would make it 10x slower.
Example:
// DO NOT REFACTOR - This caching strategy is fragile
// but dropping it caused 2 second latency increase
// See: incident-2022-03-14
private static Dictionary<string, CachedResult> _cache = new();
private static object _lockObj = new();
public CachedResult GetUser(int id) {
lock (_lockObj) {
if (_cache.ContainsKey(id.ToString())) {
return _cache[id.ToString()];
}
}
var result = FetchUserFromDb(id);
lock (_lockObj) {
_cache[id.ToString()] = result;
}
return result;
}Why is it a minefield? Because the performance characteristics are non-obvious. Removing the lock makes it faster but breaks thread safety. Improving the cache eviction strategy might change the hit rate.
Category 3: Weird Dependencies
This code has implicit dependencies on weird behavior elsewhere in the system.
Example:
# DO NOT TOUCH - relies on ordering of initialization
# If you change the order, the singleton does not initialize correctly
# See message queue setup at line 4302
class MessageQueue:
_instance = None
def __new__(cls):
if MessageQueue._instance is None:
MessageQueue._instance = super().__new__(cls)
MessageQueue._instance.connect() # Depends on global config being set
return MessageQueue._instanceWhy is it a minefield? Because the dependency is implicit. You cannot tell from reading this code that it depends on something global being initialized first. You only know it when it breaks.
I realized something while investigating:
The "DO NOT TOUCH" comment is not a warning about the code. It is a confession: "I do not understand this code."
Fear of touching code means:
The code is not inherently fragile. Your relationship with the code is.
If you had:
You would not be afraid to change it.
The "DO NOT TOUCH" comment is a symptom of knowledge debt.
I talked to engineers who had written "DO NOT TOUCH" comments. Here is why they did it:
Reason 1: They did not know why they made certain choices
"I made this code work. I do not remember all the edge cases I had to handle. If someone changes it, they might break those edge cases."
Translation: "I do not have tests for the edge cases, so I cannot trust someone to change this safely."
Reason 2: They wanted to protect future developers (themselves included)
"I spent 3 months on this. I do not want someone else wasting time redoing it."
Translation: "I did not document my learning, so the next person cannot benefit from it."
Reason 3: They were burned before
"Someone changed this once. It broke production. So now I warn the next person."
Translation: "We do not have good incident processes, so I am trying to prevent problems by discouraging changes."
Reason 4: The code is genuinely complex
"This code handles 10 different scenarios. The logic is interdependent. Changing one thing breaks another."
Translation: "This code is too complex for its own good. It needs to be refactored into smaller pieces."
In every case, the real problem is the same: knowledge debt.
When you see a "DO NOT TOUCH" comment, interpret it correctly:
What it says: "Do not modify this file."
What it means: "I am not confident you can safely modify this file. Here is why: [list your reasons]"
What it reveals: "We have a problem with knowledge transfer, testing, or code clarity."
The comment is not a solution. It is a symptom.
And symptoms do not go away. They get worse. The code gets older. More people are afraid of it. More warnings get added. Until the file is completely unmaintainable.
I found something interesting:
When one file gets the "DO NOT TOUCH" label, fear spreads.
It is cultural contagion.
One file becomes untouchable. Then the module. Then the service. Then nobody wants to work on that service because "everything is fragile."
And here is the worst part: the files are actually fine. The problem is the culture of fear. The problem is knowledge debt.
Do not just leave the comment. Fix the problem.
Step 1: Understand the code
Read the code. Ask the original developer (if they are still around). Read git history. Find out why it looks the way it does.
Step 2: Write tests
Write tests for every edge case the code handles. Make the behavior explicit. Once you have tests, you can change the code safely.
Step 3: Document the assumptions
Write down why the code is this way. What assumptions does it make? What would break if changed?
// This function calculates discount based on user VIP level and purchase date.
//
// Business rule: Bulk orders get 15% discount on Wednesdays, but only for VIP users
// in regions where VIP threshold is high.
//
// This is fragile because:
// - Discount logic is tightly coupled to date logic
// - Region thresholds are magic numbers (should be config)
//
// DO NOT change without:
// - Understanding the business rule
// - Running the full test suite
// - Talking to the business team
function calculateDiscount(order, user, date, region) {
// ... code
}Step 4: Refactor safely
Once you have tests and documentation, refactor the code. Break it into smaller functions. Make the intent clear. Make it maintainable.
Step 5: Remove the warning
Once the code is understood, tested, and documented, remove the "DO NOT TOUCH" warning. Replace it with normal code.
The "DO NOT TOUCH" comment reveals something we do not like to admit:
We are all writing code we are not confident about.
We write code that works. We do not test it thoroughly. We do not document it. Then we move on. Six months later, we are nervous about it. A year later, it is a minefield.
The "DO NOT TOUCH" comment is a badge of shame. It says: "I did not do a good job here."
But here is the thing: it does not have to be this way.
If you spent one more day:
Then the next developer would not be afraid. The file would be maintainable. Knowledge would be transferred.
But we do not do that. We move on. We write the "DO NOT TOUCH" comment. And we create knowledge debt.
