Originally published on decentphp.dev — part of the Writing decent PHP course. View this lesson on the original site.
Turn Chapter 1 into an action plan
You have now covered naming, clarity, code rot, verification, and trade-offs.
This lesson is about turning those ideas into one practical plan for your real codebase.
Step 1: pick one target area
Choose one area that is both important and uncomfortable:
- changed frequently
- unclear to new team members
- known for regressions
- avoided in reviews because it is risky
Do not pick three areas. Pick one.
Step 2: define the problem in plain language
Write one short sentence:
- "This area slows us down because..."
- "This area causes bugs because..."
- "This area is hard to reason about because..."
If you cannot explain the problem clearly, do not start refactoring yet.
Step 3: choose one Chapter 1 lever
Use exactly one lever first:
- clearer naming
- smaller function boundaries
- flatter control flow with early returns
- explicit dependencies
- one verification check before merge
Small wins create momentum. Big plans often stall.
Step 4: set a success signal
Pick one measurable signal:
- fewer review comments asking for clarification
- faster completion time for similar changes
- fewer regressions in that area
- easier handover between teammates
Without a signal, improvement becomes opinion.
Step 5: keep scope disciplined
Before you start, decide what you will not change this week.
Scope control is what keeps a cleanup effort from turning into a rewrite.
Useful wording for PRs:
- "This change improves naming and flow only."
- "No behaviour changes intended."
- "Architecture changes are intentionally out of scope."
Why this lesson matters
1.13 showed you where the course is going.
1.14 tells you how to start applying it safely.
1.15 then gives you guided practice with tighter constraints.
From Writing decent PHP — What decent PHP looks like