Keeping changes small

Jovanus Hartono

A small change is easier to review and easier to undo. These are the checks I run before I call one done.

Write less

  • Write the least code that solves the problem, and nothing speculative.
  • Skip options, flags and settings nobody asked for.
  • Don't build an abstraction for code that's used once. Three similar lines are easier to read than the helper that replaces them.
  • Validate where data comes in from outside, like user input and other people's APIs. Inside your own code, don't handle errors that can't happen.
  • If 200 lines could be 50, rewrite it.
  • If there's a simpler way than the one you were asked for, say so before building the one you were asked for.
  • Ask whether a senior engineer would call it overcomplicated. If the answer is yes, simplify first.

Touch only what the task needs

  • Every changed line should trace back to the request.
  • Match the style around you, except for the rules you've decided always apply. Mine are in How I write React.
  • Leave nearby code, comments and formatting alone. Tidying them on the way past makes the diff harder to review.
  • If you spot dead code that isn't yours, mention it and leave it. Remove only the leftovers your own change created.

Before the pull request

  • Do a simplify pass over the final diff. Whoever wrote it, and coding agents especially, tends to over-deliver: an extra helper, an extra parameter, a comment on every hunk. That's cheaper to strip before review than after merge.
  • Run the checks again afterwards, since cutting code can break it.