🧹 Refactoring & Technical Debt

The Senior Mindset: Technical debt is not necessarily “bad code.” It is a strategic tool. Like financial debt, it can help you move faster now, provided you have a clear plan to pay it back before the “interest” (complexity and bugs) halts development.

---

📉 Understanding Technical Debt

Technical debt is the implied cost of additional rework caused by choosing an easy (limited) solution now instead of using a better approach that would take longer.

The Technical Debt Quadrant

1. Reckless & Deliberate: “We don’t have time for design/tests.” (Dangerous)
2. Prudent & Deliberate: “We must ship now and deal with the consequences later.” (Strategic)
3. Reckless & Inadvertent: “What’s a Layered Architecture?” (Incompetence)
4. Prudent & Inadvertent: “Now that we’ve built it, we finally understand how we should have designed it.” (Learning)

---

🛠️ The Art of Refactoring

Refactoring is the process of changing a software system in such a way that it does not alter the external behavior of the code yet improves its internal structure.

Core Principles

• Small Steps: Never refactor and add features in the same commit.
• Test-Driven Safety: You cannot safely refactor without a robust suite of Unit and Integration tests. If you don’t have tests, your first “refactoring” step is writing them.
• The Boy Scout Rule: Always leave the code slightly cleaner than you found it.

Common Techniques

• Extract Method: Breaking down long functions into smaller, descriptive ones.
• Replace Temp with Query: Avoiding local variables that clutter logic.
• Move Method/Field: Placing logic where it naturally belongs (Cohesion).

---

⚖️ Managing Debt (The Senior Perspective)

1. When to Refactor?

• Rule of Three: The first time you do something, you just do it. The second time, you wince at the duplication. The third time, you refactor.
• The Pain Point: Only refactor code that you actually need to touch. Refactoring a “messy” module that hasn’t been changed in two years is often a waste of company resources.

2. Communicating Debt to Stakeholders

Avoid technical jargon. Instead of saying “We need to decouple these classes,” say:

“This area of the code is fragile. If we don’t spend two days cleaning it now, every new feature in this module will take twice as long to build next month.”

3. Measuring Debt

• Code Complexity (Cyclomatic): How many paths exist through the code?
• Change Velocity: How long does it take to ship a feature now vs. six months ago?
• Bug Frequency: Does touching “Module X” always result in a regression?

---

🚩 Code Smells to Watch For

• God Objects: Classes that try to do everything.
• Shotgun Surgery: One small change requires editing 10 different files.
• Primitive Obsession: Using strings or integers for concepts that should be objects (e.g., string email vs EmailAddress type).

💡 Seniority Note: “Perfect is the enemy of the good.” Avoid Over-engineering. Sometimes, a “hack” is the correct business decision if it validates a product hypothesis. The senior’s job is to ensure that the hack is documented and tracked as debt, not forgotten.

---

🔗 Related Links

• [[Clean-Architecture]]
• [[Quality-Testing-Strategies]]
• [[Lideranca-Gestao-Prioridades]]