200apps Corpus

Appearance

Development & Code · master area

Refactoring ​

Improving the shape of the code without changing what it does. Travels with the cycle, in service of a brief — not as a separate "refactor week" that never proves its value.

Owners: Developer, Tech Lead Phase it lives in: How We Build (Volume IV) The corpus principle this enacts: Technical debt is unresolved decisions in the chain — refactoring is how decisions are resolved.

Where it lives in the chain ​

How to do this ​

  • Practice — refactor in service of a brief. The story to ship the new behaviour is also the story to clean up the shape it sits in. Refactoring without a destination is sculpting a code-base that nobody asked for.
  • Practice — refactor under green tests. The unit tests guard the behaviour while the shape changes. No tests, no refactor — first write the test, then refactor.
  • Practice — one refactoring per PR. Reviewer can read it. A PR that mixes behaviour change and shape change is a PR nobody reads carefully.

What good refactoring looks like ​

A new story arrives: add idempotency to the grading submit. The developer looks at submitExam and finds it tangled with retry logic, logging, and stale comments. Before adding idempotency, the developer extracts the retry into its own function, names it retryWithBackoff, deletes the stale comments, and runs the tests — same behaviour, cleaner shape. Then the idempotency change goes in. The PR contains two commits: "refactor: extract retry from submitExam" and "feat: add idempotency to submitExam (GR-211)."

A team that refactors in service of cycles compounds its understanding of the domain into the code. A team that refactors separately — or never — leaves understanding to walk out the door with the developer who held it.

200apps · How We Work · NWIRE

Internal corpus. Voice and structure © 200apps.