Skip to content
Tutorials Center
My learning

Topics

Lesson 36 of 37 ยท Projects and Practice

Project: A Clean as You Code Workflow for a Legacy Codebase

Plan a Clean as You Code programme for a legacy codebase: triage the baseline, protect new code, pay debt in touched files, track trends, and report progress with scripts you can run.

Legacy code is the normal case. A system with 400,000 lines and 6,000 open issues cannot be fixed in a sprint, and a gate that demands zero issues everywhere would never go green. Clean as You Code is the answer: keep new and changed code clean, and let the legacy shrink naturally as it is touched. This project turns that idea into a working routine for a team, with rules, a weekly cadence and small tools to measure progress.

SonarQube is not runnable on this site, so the UI steps are described in words and the TryIts are stand-ins for the calculations.

The principle

The total of old issues is called the overall code debt; the new code is everything added or changed since the new code period started. Quality gates on new code mean:

  • Old problems do not block anyone.
  • No new problem can enter (the leak is stopped).
  • Over time, because most active files get edited, the overall debt falls without a big-bang refactor.
flowchart LR
  A["Baseline: legacy debt"] --> B["Gate on new code only"]
  B --> C["Every change is clean"]
  C --> D["Touched legacy gets fixed in passing"]
  D --> E["Overall debt falls over time"]

Figure: the loop that makes legacy debt shrink without a rewrite.

Week 0: triage the baseline

  1. Run the first analysis and open the project overview with the Overall Code tab.
  2. Record the starting numbers. Keep this small table in the repository wiki:
Metric Value
Lines of code 400,000
Bugs 120
Vulnerabilities 15
Hotspots to review 340
Debt 310 days
Coverage 38%
  1. Vulnerabilities first. Open the list sorted by severity. Fix or schedule every one; vulnerabilities do not wait for clean-as-you-code.
  2. Hotspots next. Run a review session with security champions (see Reviewing security hotspots) on High priority hotspots. Most land on Safe with a comment.
  3. Bugs. Triage by severity; fix blockers and criticals, schedule the rest.
  4. Code smells. Leave them. Do not bulk-fix a quarter of a million minutes.

Week 1: turn on protection

  • Set the new code period. Good choices: Reference branch = main for trunk-based teams, Previous version if you ship numbered releases, or Number of days (for example 30) if you want a rolling window.
  • Assign the Sonar way gate (or a tuned copy) and enforce it on pull requests (see Pull request analysis).
  • Tell the team: "You are not responsible for the old red numbers. You are responsible for your diff."

Daily habits

  1. Install SonarQube for IDE in connected mode so you see issues while typing, using the server's rules (same quality profile).
  2. Before you push, read the issues on your changed lines.
  3. When you edit a file with old issues, fix the cheap ones (a few minutes each) in the same change if they are close to your edits. This is the "boy scout rule".
  4. Do not mix large refactors into feature PRs; use a separate PR so the gate and reviewers can focus.

Weekly cadence

  • Monday: look at the trend of overall debt and new code issues.
  • Review the five files with the highest debt that were edited recently (hot files); these are the best refactoring candidates, because they will be touched again.
  • Review any pull requests merged with a failing gate (there should be none, or a documented exception).
  • Review new hotspots stuck in To Review.

Stand-in: pick files worth cleaning

Not every messy file deserves attention. A file that is messy and never changes costs nothing; a messy file that changes weekly costs a lot. This stand-in ranks files by debt x churn, an approach called hotspot analysis of churn and complexity.

JS Stand-in: rank files by debt and churn

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Stand-in: simulate the trend

Does the approach really shrink debt? This simulation models weekly work: new code is added clean, and a fraction of existing debt is paid down when files are touched. The numbers are illustrative assumptions, not measured results.

JS Stand-in: overall debt under Clean as You Code

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The shape matters more than the numbers: when new debt stops, even a slow pay-down wins; when new debt keeps entering, the system never improves.

Reporting progress to managers

Use three numbers and avoid dashboards of twenty metrics:

  1. Issues in new code per month (target: 0, since the gate blocks them).
  2. Vulnerabilities and unreviewed hotspots in overall code (target: falling to 0).
  3. Coverage on new code and, secondarily, overall coverage.

Pull them via the Web API once a month into a spreadsheet, plus the remediation effort trend (sqale_index) for the story.

Pitfalls

  • Resetting the new code period constantly hides the real state. Change it deliberately and rarely.
  • Setting everything to "Accepted" or "False positive" to get a green dashboard.
  • Running a "fix all smells" week that creates conflicts and bugs. Prefer small changes in touched files.
  • No owner. Name a quality champion who watches trends and chases exceptions.

Check your understanding

Quick check ยท 3 questions

of 3 answered You scored / 3 ยท perfect!

  1. 1. What is the core idea of Clean as You Code?

    The gate applies to new code, which stops the leak while old code improves gradually.
  2. 2. Which findings should be handled first in the baseline triage?

    Security issues carry the highest risk and should not wait.
  3. 3. Why rank files by debt multiplied by churn?

    A messy but untouched file costs little; a messy file edited weekly costs a lot.

Summary

  • Triage the baseline: vulnerabilities and hotspots first, then bugs; leave smells.
  • Gate new code, enforce on pull requests, and use SonarQube for IDE for fast feedback.
  • Clean cheap issues in files you touch, and target high-churn, high-debt files.
  • Report a few meaningful numbers and avoid resetting the new code period.

Next: Practice questions and exercises