The Merge Conflict Mediator
When two senior developers discover they've been violently agreeing
The conference room had that particular tension that comes from two brilliant people who both think they're right.
James sat on one side of the table, his laptop open to a detailed refactoring proposal he'd spent three days preparing. Across from him, Priya had her laptop open with a completely different approach—one she'd also spent three days on.
Their CTO, Sandra, looked like she hadn't slept well. This was the third meeting about restructuring their e-commerce platform's authentication system, and they were no closer to agreement than they'd been two weeks ago.
"We need to separate concerns," James said, pulling up his architecture diagram for what felt like the hundredth time. "Move all the user validation into a separate service layer. It's basic SOLID principles."
Priya's jaw tightened. "That's exactly what I'm proposing! But you keep rejecting my pull request."
"No," James shook his head, "you're coupling the validation with the ORM models. It's the exact opposite of separation of concerns."
"I'm not coupling anything!" Priya's voice rose slightly. "The validation service is completely independent of the models."
Sandra held up a hand. "Okay, timeout. I can't tell if you're proposing the same thing with different words, or if I'm missing something fundamental here. Show me both architectures. Clearly."
The Whiteboard Session
They both stood and moved to the whiteboard. James grabbed a blue marker and started drawing boxes. "See, the models layer here, then the validation layer above it—"
Priya picked up a red marker and drew on the other side. "Right, and that's what I have. Models at the bottom, validation as a separate concern—"
Boxes. Arrows. Layers labeled "Service" and "Domain" and "Infrastructure." More boxes. The diagrams looked similar but not quite identical. Were they the same? Different? After thirty minutes, no one could tell anymore.
Sandra stared at the whiteboard, then at James's laptop, then at Priya's laptop. "I'm going to be honest with you both. I cannot tell if these are the same thing or completely different approaches. And if I can't tell, after fifteen years of software architecture, we have a communication problem."
The Quiet Voice
Emma, a junior developer who'd been quietly sitting in the corner taking notes, spoke up for the first time. "Um, could we just... look at the actual code structure? I mean, not read through all the files, but actually see the structure?"
Three pairs of eyes turned toward her.
"I've been using this tool called Python Structure Viewer," she continued, a bit nervous now. "It shows you what's actually in your Python files—the classes, functions, how things connect. Maybe if we just looked at the actual structure instead of arguing about descriptions of the structure?"
James looked skeptical. "We're talking about architecture, not code formatting."
But Sandra was already nodding. "At this point, anything's worth trying. Emma, can you show us?"
The Projection
Emma plugged her laptop into the conference room projector. Her hands shook slightly as she pulled up the terminal—this was definitely the most senior audience she'd ever presented to.
"Okay, so this is our current auth/models.py file," she said, running Python Structure Viewer on the main branch.
The output appeared on the wall:
=== TREE VIEW ===
ImportFrom
validate_user_email(email)
'Validation mixed into models file'
If not email or '@' not in email
└── Return False
domain = email.split('@')[1]
blocked_domains = ['spam.com', 'fake.net']
Return domain not in blocked_domains
class User
email = models.EmailField()
username = models.CharField(max_length=100)
is_active = models.BooleanField(default=True)
save(self)
If not validate_user_email(self.email)
└── Raise
super().save(*args, **kwargs)
check_permissions(self, resource)
'Business logic mixed with model'
If not self.is_active
└── Return False
Return True
get_active_users()
'Query helper mixed into models'
Return User.objects.filter(is_active=True)
"So you can see," Emma said, pointing at the screen, "we've got validation functions, the User model, business logic methods, and query helpers all mixed together in one file."
Priya nodded slowly. "Right. That's the problem we're both trying to solve."
"Okay," Emma said, switching to James's branch. "Now here's James's refactored version of the same file."
=== TREE VIEW ===
ImportFrom
ImportFrom
class User
email = models.EmailField()
username = models.CharField(max_length=100)
is_active = models.BooleanField(default=True)
save(self)
If not validate_user_email(self.email)
└── Raise
super().save(*args, **kwargs)
"Much cleaner," James said. "The validation logic is extracted to its own module."
"Now let me show Priya's version," Emma said, and switched branches.
The exact same structure appeared on the screen.
=== TREE VIEW ===
ImportFrom
ImportFrom
class User
email = models.EmailField()
username = models.CharField(max_length=100)
is_active = models.BooleanField(default=True)
save(self)
If not validate_user_email(self.email)
└── Raise
super().save(*args, **kwargs)
The Silence
Nobody spoke for a solid ten seconds.
James leaned forward, squinting at the screen. "Wait. That's..."
"Identical," Priya said quietly. "The structures are identical."
"But you said—" James started.
"You told me I was coupling the validators with the models," Priya said, her voice careful, controlled.
"Where did you put the validation function?" James asked.
"In auth/validation/rules.py."
"I put mine in auth/validators/user_rules.py."
Another silence.
"Same directory depth," Priya said.
"Same separation from models," James said.
"Same import pattern."
"Same extracted logic."
Sandra started laughing. Actually laughing, her head in her hands. "You've been arguing about file naming conventions for three weeks. Three weeks! Do you know how many features we could have shipped?"
The Aftermath
James and Priya looked at each other across the table. The tension in the room had transformed into something else—sheepishness, maybe, mixed with the kind of exhausted relief that comes from realizing a problem isn't actually a problem.
"Your docstrings are better," Priya admitted.
"Your file naming is clearer," James said. "The team will find validation/rules.py more intuitive than validators/user_rules.py."
"So we use your naming scheme with my documentation style?"
"Yeah. Yeah, that works."
They merged both pull requests that afternoon—Priya's file structure with James's more detailed docstrings and type hints. The refactor shipped to production the next day. No bugs. No incidents. Just a cleaner, more maintainable authentication system that both architects had essentially designed in parallel without realizing it.
Two Months Later
Marcus, a new senior hire, was presenting his proposal for restructuring their payment processing system. He'd prepared an elaborate PowerPoint with UML diagrams and architectural decision records.
Halfway through his third slide, James and Priya exchanged a look.
"Marcus," Priya said gently, "before we spend three meetings debating this..."
"Emma," James called across the table, "could you run Marcus's branch through the Python Structure Viewer?"
Marcus looked confused. "The what?"
Emma was already pulling up her laptop, grinning. "Let me show you how we actually make architectural decisions around here."
She plugged into the projector. "This is your current payment processor..."
Marcus watched as the tangled structure of the existing code appeared on the wall, then the clean separation in his proposed refactor. The visual made his thirty-slide deck unnecessary. The team could see what he was proposing in seconds rather than trying to parse it from boxes and arrows.
"That's..." Marcus said, "that's actually really useful."
"We learned the hard way," Sandra said, "that the best way to end an architecture debate is to stop talking about the architecture and just look at it."
About Python Structure Viewer
Python Structure Viewer is an free tool that analyzes Python source code and presents its structure in both tree and natural language formats. It shows classes, functions, methods, control flow, and dependencies at a glance—turning abstract architectural discussions into concrete, visual comparisons.
Sometimes the best way to win an argument is to discover you weren't actually having one.
Want to avoid your own three-week naming convention debate? Download Python Structure Viewer and see your code's structure clearly.
Aaron Rose is a software engineer and technology writer at tech-reader.blog and the author of Think Like a Genius.
Comments
Post a Comment