A team inherits a billing module that nobody fully understands. It has no tests that protect existing behaviour. A sprint is proposed to “clean it up”, and the plan is to rewrite the core in a new structure. Nobody can say how they would know that the new version still charges customers correctly.
This is an illustrative scenario, not a documented incident. It describes the gap a refactoring training project has to close: engineers who can see that code is messy, but cannot yet plan a bounded improvement and show that behaviour was preserved.
This guide is for engineering enablement leads and engineering managers. It covers how to describe the performance problem, diagnose the gaps, design preparation and practice, work through a case and assess whether the skill transfers to real work. It is about training design. The code, tests and rules in your programme should be validated by senior engineers on your own stack.
What is a refactoring training project?
A refactoring training project is a structured piece of work on legacy code, where the purpose is to build capability as well as to improve the code. Learners plan a small, bounded change, protect existing behaviour with tests, improve the design in small steps and show evidence that nothing broke. The code gets better, and, more importantly, the engineers practise the judgement they will need on real technical debt.
Gyors tények
| Kérdés | Rövid válasz |
|---|---|
| Mi a feladat? | Plan and validate a bounded legacy code improvement. |
| What do you score? | Risk analysis, and evidence that existing behaviour was preserved. |
| Is a broad rewrite a good training project? | Usually not. It hides the skill being practised and makes preserved behaviour hard to show. |
| Is a quiz on refactoring patterns enough? | No. It confirms prerequisites, but not whether an engineer can plan and validate a change. |
| Who validates the content? | An engineering manager and a senior engineer who knows the codebase. |
| What can training not fix? | Missing test tooling, release pressure, unclear ownership and no time for maintenance work. |
| How do you know it worked? | A new, unseen legacy-code case, scored against agreed criteria, with follow-up on real work. |
1. Describe the performance problem
Start with the task: plan and validate a bounded legacy code improvement. “Bounded” is the important word. The learner chooses a change small enough to finish, and can say what is in and out of scope.
It helps to be precise about terms. Martin Fowler describes refactoring as a controlled technique for improving the design of an existing code base, made up of small, behaviour-preserving transformations. The phrase “behaviour-preserving” is what separates refactoring from a rewrite, and it is what the training must make visible. The technical debt metaphor itself was coined by Ward Cunningham, and Fowler's discussion is a useful reminder that debt can be taken on deliberately and prudently, so not every messy module is a mistake to be fixed.
Michael Feathers' book on legacy code takes the same line on practice. Its publisher's description says it teaches developers to write tests that ensure they are not unintentionally changing the application, and to bring existing software under control without a full rewrite.
Write the performance statement in one sentence and have an engineering manager check it: “Given a legacy module and a defined goal, the engineer proposes a bounded change, adds tests that pin down current behaviour, makes the change in small steps and shows that behaviour is preserved.”
2. Diagnose the learning and context gaps
Before you build anything, compare the required task with what your current activities practise and assess. Three questions usually separate a training gap from something else:
- Does current practice use the real task? If training covers refactoring patterns in slides, but nobody ever changes untested code, no one has practised protecting behaviour. If assessment is a multiple-choice test on code smells, it measures recall.
- What is the cognitive demand? In Bloom's revised taxonomy, judging whether a change is safe sits at the analyse and evaluate levels, and designing the plan and the tests reaches the create level. Matching activities to those levels is covered in our guide to tanulási tevékenységek Bloom taxonómiájához való illesztése.
- Is something other than skill getting in the way? Check staffing, tools and procedures. If the build takes an hour, nobody will run tests often. If maintenance work is never scheduled, engineers will only refactor in secret. Report non-training causes to the people who can fix them.
3. Design purposeful preparation and practice
Once you know which gaps training can close, give each stage a distinct job.
Készítmény. Check prerequisites with a short diagnostic: how your test framework works, what a characterisation test is, and how your team reviews and merges. Self-paced study suits this stage. A recall check confirms prerequisites only.
Gyakorlat. Use systematic refactoring projects with a clear shape. Start on a small, safe sample, then move to a real but bounded part of your own codebase. The Gilded Rose kata is a well-known starting point for the first step. Its README, maintained by Emily Bache, recommends writing tests before changing the code and frames the exercise as practice in taking small steps, running the tests often and improving the design bit by bit. A sensible sequence for each project is: define the goal and the boundary, write tests that capture what the code does today, change one thing at a time, run the tests after every step and write down what you learned.
Visszacsatolás. Link feedback to decisions, not to a total score. “You extracted the discount logic, but your tests only covered the happy path, so you could not have noticed the rounding change” is more useful than “3 out of 5”.
Live instructor input or asynchronous review? Live input adds most value when a choice is ambiguous, for example whether to stop and add a missing test or carry on. Asynchronous review is enough when learners compare their plan and tests with an annotated expert version. Many teams use both: self-paced preparation first, then a facilitated session on the hard cases.
4. Work through a realistic example
Illustrative. An engineering manager should validate the case and the answer criteria before use.
Az eset. A legacy function calculates an order total, including a discount, tax and a shipping rule. It has no tests. A team proposes to restructure the whole billing module to make it “cleaner”.
A feladat. The learner explains what they would do, cites the evidence they would gather, and says what further information or support they need.
A first attempt. “I would split the module into three services and move the logic over, then check the numbers in staging.” The learner has chosen a large change and a late, manual check. There is no way to tell whether the old and new versions agree on edge cases.
Visszajelzés és újrapróbálás. The reviewer asks what the function does today for an empty basket, a discount that makes the total negative, and a rounding case. The retry asks the learner to narrow the scope to one behaviour and to say how they would prove it did not change.
A stronger attempt. “I would leave the module structure alone for now. I would capture what the order total function returns today for a set of inputs, including the edge cases, as tests. Then I would extract the discount calculation into its own function, run the tests after that single step, and stop. I would note that the shipping rule has behaviour I do not understand and ask a colleague before touching it.” Notice that this answer bounds the change, protects behaviour first and names what is unknown.
Why each response is defensible or incomplete. Judge each against approved criteria, not a reviewer's preference. The first attempt may be a sensible long-term direction but is incomplete as a plan, because it carries no evidence of preserved behaviour. The stronger attempt is small, checkable and honest about uncertainty.
5. Assess capability and plan transfer
Evidence of capability is performance on a new legacy-code case the learner has not seen. Score the risk analysis and the evidence that behaviour was preserved. A simple rubric uses a 0 to 2 scale per criterion:
| Kritérium | Megfigyelhető bizonyítékok |
|---|---|
| Feladat végrehajtása | Plans and validates a bounded legacy code improvement, and records the action and the evidence behind it. |
| Érvelés | Explains the constraints, alternatives and uncertainty, and checks the risks and the evidence that behaviour was preserved. |
| Határok | Uses approved procedures, and asks for help when information or authority is insufficient. |
Anchors: 0 is absent or unsupported, 1 is partial with relevant omissions, and 2 is complete and justified against agreed criteria. Define critical errors separately, such as changing behaviour with no test that would have noticed, so an overall score cannot hide one. This rubric is a proposal, not a validated readiness standard: adapt it with an engineering manager and pilot it. Our guide to designing interactive practice with useful feedback shows how to write feedback that links to decisions.
Plan transfer deliberately. After the exercise, give each engineer a small, real piece of debt to address with a reviewer, or run a short retrospective on a recent change that broke something. Check transfer after suitable exposure to real work, not straight after the workshop.
Ahol az interaktív közvetítés segít
Interactive formats help where everyone should commit before they see the group. In a live session, a facilitator can show a short legacy snippet, ask each engineer to submit the first change they would make and how they would prove it safe, and then reveal the spread before the discussion. The same prompt can run self-paced for preparation. AhaSlides supports interactive learning and moving between live and self-paced delivery. It is a presentation and learning tool, not a place to run or analyse code, so run the refactoring itself in your own environment. Check any specific authoring, feedback or reporting function you plan to rely on against your own workflow. For guidance on choosing formats, see our article on Mikor alkalmazzunk adaptív, interaktív és élő tanulást?.
Mérd meg, mi változott
Decide in advance what would show that engineers can do the task. Compare the quality of risk analysis and the evidence of preserved behaviour on an unseen case, against a baseline. Define who is included, the denominator and the timing. If results improve, check what else changed in the same period, such as new test tooling, a faster build or a change of ownership, before crediting the training.
Maradhatnak korlátok
- Time for maintenance work. If debt work is never scheduled, trained engineers still have nowhere to use the skill.
- Test tooling. Without a usable test harness or a fast build, small steps and frequent checks are hard to sustain.
- Case coverage. One legacy case shows a few kinds of risk. A score does not describe an engineer's judgement in general.
- Judging when not to refactor. Some code is better left alone, replaced or retired, and that decision involves more than skill.
- Átadása. Performance in a kata is not the same as performance in a production module under delivery pressure.
Name these to sponsors early and plan separate fixes. Training improves what an engineer can plan and prove. It does not create the time or the tooling.
Gyakran Ismételt Kérdések
What is a refactoring training project?
It is structured practice on legacy code where engineers plan a small change, protect existing behaviour with tests, change the design in small steps and show that nothing broke.
Is a full rewrite a good way to learn about technical debt?
Usually not. A rewrite is large, hard to validate and hides the skill you want to build. A bounded change with tests that capture current behaviour makes the reasoning visible.
How do you assess whether engineers can refactor safely?
Give a new legacy-code case and score the risk analysis and the evidence that behaviour was preserved against agreed criteria. A quiz on refactoring patterns confirms prerequisites only.
Do you need a sample codebase for the training?
You need somewhere to practise safely. Many teams start with a public kata and then move to a bounded part of their own code. Your engineering manager should confirm the code is suitable.
Hol kezdjem
Pick one small, recurring kind of legacy change in your codebase. Write the performance statement, have an engineering manager validate the case and the tests that would show preserved behaviour, and draft a three-criterion rubric with a 0 to 2 scale and a list of critical errors. Pilot it with a small group before you roll it out.
To see how a refactoring decision exercise could run live with your own team, and be reused self-paced afterwards, explore AhaSlides.
