Narrating Code Changes — Before and After Vocabulary
Learn vocabulary for describing code changes in pull requests and reviews: what changed, why, and how it improves the code.
0 / 5 completed
1 / 5
What is the purpose of a 'refactoring PR description' and what should it include?
A refactoring PR description should cover: WHAT changed (e.g., extracted PaymentProcessor class from OrderService), WHY (OrderService had 15 responsibilities and 800 lines), behavior contract (no behavior changes — all existing tests pass), and verification steps (run test suite, check integration tests).
2 / 5
What does 'no behavior change' mean in a refactoring PR?
'No behavior change' is the core contract of refactoring: the external observable behavior (output, side effects, API) is identical — only the internal implementation improved. This is proven by having a complete test suite that passes before and after the refactoring.
3 / 5
How do you describe an 'Extract Method' refactoring in a PR?
Precise refactoring language: 'Extracted validatePaymentDetails() from processOrder() — this isolates payment validation logic, allows independent testing, and reduces processOrder() from 80 to 35 lines.' Naming the refactoring type, source, destination, and improvement helps reviewers understand intent and scope.
4 / 5
What is the 'explain the why, not the what' principle in code narration?
Good PR descriptions (and comments) explain WHY: 'We use a two-phase commit here because the payment and inventory systems must succeed or fail atomically — a naive single-phase approach caused split-brain incidents in Q2 2023.' The WHAT is visible in the diff — the WHY is not.
5 / 5
What is 'regression risk' in a refactoring context?
Regression risk in refactoring: structural changes may inadvertently alter behavior. Mitigation: comprehensive test suite coverage before refactoring, small incremental refactoring steps (not giant rewrites), CI pipeline that catches regressions, and characterization tests for legacy code without tests.