How to Deal with a Messy Coding Guideline

What Would You Do?#

How does your team define coding guidelines or team conventions? Were they already in place when you joined, or did they evolve over time?

If the existing rules now create high maintenance costs and risk adding more chaos later, what would you do?

I can’t speak for your answer—but here’s what I did.

I’ve built collaboration culture from scratch and revised long-standing conventions before. Still, nothing compares to this particular journey. Let me explain.

The First Wall After Onboarding#

After onboarding, most engineers want to show quick impact.

I was no different. My first few deliveries went smoothly—until I tried to align with the coding guidelines. That’s when I hit a wall. The team’s suggested style left me unsure where to draw boundaries, and even code written in the same period followed different rules.

What would you do?

• A: This codebase is messy—just write and move on.
• B: Feels off, but ship it first and maybe revisit later.
• C: Something’s wrong. I’m going to fix it.

I started with A, settled into B, and eventually acted on C.

The end.

Not really.

The Problem Is Lack of Resolution#

Here’s why.

I didn’t fully understand the reasoning behind the coding guidelines, but I accepted the status quo at first. I needed to earn credit and show I could deliver. Meanwhile, I started asking teammates questions:

Why do we have different styles in code written around the same time?
Is it a business requirement or just legacy drift?
Should we schedule refactoring time or fix as we go?

What principle drives our style rules?
If it’s extensibility, is that still our top priority?

I learned that everyone had opinions. Some great discussions happened during reviews, but never reached the full team. Others were buried in old threads without a conclusion.

To me, both meant no resolution:

• In reviews, insights stay between author and reviewer.
• In threads, debates stay lively but directionless.

Without shared conclusions, code reviews don’t help the team grow—they just widen inconsistencies.

Proposal#

I went to R (my longtime engineering manager) and asked:
“Is it true most of our technical discussions never reach a conclusion?”

He said yes.

So I suggested trying a new approach—showing how I’d handle team-wide decisions.

I chose a small archived style issue, collected feedback, merged opinions, and reached consensus. Then I set two action items:

• Update the coding guidelines doc
• Adjust the linter rules

Only when both were done did I consider the proposal complete.

After that, I proposed a process for proposals, with four phases:

1. Proposal
   State the background, related research, suggested approach, and sample code.

2. Discussion
   Like an RFC, open to all members. Agreement is marked; disagreement must include reasoning. Continues until consensus.

3. Conclusion
   Proposal owner consolidates agreements and action items. Final review allows objections before approval.

4. Action
   Owner executes the plan, with help if needed. If extra resources are required, the EM steps in. Only when all actions are complete is the proposal closed.

This Became the New Norm#

The process might sound heavy, but soon everyone started using it.

It gave direction to discussions and made decisions stick.

I didn’t realize it then, but breaking down root issues, clarifying how we decide, and making sure changes were carried through became a defining trait for me—and a big reason I grew into a Staff role.