Refactoring at Scale

Table of contents

1. Preface
   1. Who Should Read This Book
   2. Why I Wrote This Book
   3. Navigating This Book
   4. Conventions Used in This Book
   5. Using Code Examples
   6. O’Reilly Online Learning
   7. How to Contact Us
   8. Acknowledgments
2. I. Introduction
3. 1. Refactoring
   1. What Is Refactoring?
   2. What Is Refactoring at Scale?
   3. Why Should You Care About Refactoring?
   4. Benefits of Refactoring
      1. Developer Productivity
      2. Identifying Bugs
   5. Risks of Refactoring
      1. Serious Regressions
      2. Unearthing Dormant Bugs
      3. Scope Creep
      4. Unnecessary Complexity
   6. When to Refactor
      1. Small Scope
      2. Code Complexity Actively Hinders Development
      3. Shift in Product Requirements
      4. Performance
      5. Using a New Technology
   7. When Not to Refactor
      1. For Fun or Out of Boredom
      2. Because You Happened to Be Passing By
      3. To Making Code More Extendable
      4. When You Don’t Have Time
   8. Our First Refactoring Example
      1. Simplifying Conditionals
      2. Extracting Magic Numbers
      3. Extracting Self-Contained Logic
4. 2. How Code Degrades
   1. Why Understanding Code Degradation Matters
   2. Requirement Shifts
      1. Scalability
      2. Accessibility
      3. Device Compatibility
      4. Environmental Changes
      5. External Dependencies
      6. Unused Code
      7. Changes in Product Requirements
   3. Tech Debt
      1. Working Around Technology Choices
      2. Persistent Lack of Organization
      3. Moving Too Quickly
   4. Applying Our Knowledge
5. II. Planning
6. 3. Measuring Our Starting State
   1. Why Is Measuring the Impact of a Refactor Difficult?
   2. Measuring Code Complexity
      1. Halstead Metrics
      2. Cyclomatic Complexity
      3. NPath Complexity
      4. Lines of Code
   3. Test Coverage Metrics
   4. Documentation
      1. Formal Documentation
      2. Informal Documentation
   5. Version Control
      1. Commit Messages
      2. Commits in Aggregate
   6. Reputation
   7. Building a Complete Picture
7. 4. Drafting a Plan
   1. Defining Your End State
      1. On the Road
      2. At Work
   2. Mapping the Shortest Distance
      1. On the Road
      2. At Work
   3. Identifying Strategic Intermediate Milestones
      1. On the Road
      2. At Work
   4. Choosing a Rollout Strategy
      1. Dark Mode/Light Mode
      2. Smart DNA’s Rollout
   5. Cleaning Up Artifacts
   6. Referencing Metrics in Your Plan
      1. Interpolating Goal Metrics to Intermediate Milestones
      2. Distinct Milestone Metrics
   7. Estimating
   8. Sharing Your Plan with Other Teams
      1. Transparency
      2. Perspective
   9. Refined Plan
8. 5. Getting Buy-In
   1. Why Your Manager Is Not Onboard
      1. Managers Aren’t Coding
      2. Managers Are Evaluated Differently
      3. Managers See the Risk
      4. Managers Need to Coordinate
   2. Strategies for Making a Compelling Argument
      1. Using Conversational Devices
      2. Building an Alignment Sandwich
      3. Relying on Evidence
      4. Playing Hardball
   3. Buy-In Shapes the Refactor
9. 6. Building the Right Team
   1. Identifying Different Kinds of Experts
   2. Matchmaking
      1. Experts of Many Trades
      2. Revisiting Active Contributors
      3. Biases in Our Expert List
   3. Types of Refactoring Teams
      1. Owners
      2. Proposed Approach
      3. Cleanup Crews
   4. The Pitch
      1. Metrics
      2. Generosity
      3. Opportunity
      4. Bartering
      5. Repeat
   5. A Few Outcomes
      1. Realistic Scenario
      2. Worst-Case Scenario
   6. Fostering Strong Teams
10. III. Execution
11. 7. Communication
    1. Within Your Team
       1. Stand-Ups
       2. Weekly Syncs
       3. Retrospectives
    2. Outside Your Team
       1. When Kicking Off the Project
       2. During Project Execution
    3. Always Iterate
12. 8. Strategies for Execution
    1. Team Building
       1. Pair Programming
       2. Keeping Everyone Motivated
    2. Keeping a Tally
       1. Intermediate Metric Measurements
       2. Unearthed Bugs
       3. Clean-Up Items
       4. Out-of-Scope Items
    3. Programming Productively
       1. Prototyping
       2. Keep Things Small
       3. Test, Test, Test
       4. Asking the “Stupid” Question
    4. Conclusion
13. 9. Making the Refactor Stick
    1. Fostering Adoption
    2. Education
       1. Active Education
       2. Passive Education
    3. Reinforcement
       1. Progressive Linting
       2. Code Analysis Tools
       3. Gates Versus Guardrails
    4. Integrating Improvement into the Culture
14. IV. Case Studies
15. 10. Case Study: Redundant Database Schemas
    1. Slack 101
    2. Slack Architecture 101
    3. Scalability Problems
       1. Booting Up the Slack Client
       2. File Visibility
       3. Mentions
    4. Consolidating the Tables
       1. Gathering the Scattered Queries
       2. Developing a Migration Strategy
       3. Quantifying Our Progress
       4. Attempting to Keep the Team Motivated
       5. Communicating Our Progress
    5. Tidying Up
    6. Lessons Learned
       1. Develop a Well-Defined, Well-Communicated Plan
    7. Understand the Code’s History
       1. Ensure Adequate Test Coverage
       2. Keep Your Team Motivated
       3. Focus on Strategic Milestones
       4. Identify and Rely on Meaningful Metrics
    8. Takeaways
16. 11. Case Study: Migrating to a New Database
    1. Workspace-Sharded Data
    2. Migrating channels_members to Vitess
       1. Sharding Scheme
       2. Developing a New Schema
    3. Detangling JOINs
    4. A Difficult Rollout
       1. Backfill Mode
       2. Dark Mode
       3. Light Mode
       4. Sunset Mode
    5. Tidying Up
    6. Lessons Learned
       1. Set Realistic Estimates
       2. Source the Teammates You Need
       3. Plan Scope Carefully
       4. Choose a Single Place for Project Communication
       5. Design a Thoughtful Rollout Plan
    7. Takeaways
17. Index