CSE Roadmap

Specialist tier · about 5 hours · 13 parts

Part 4 of 13 · 2 min read

Formatting churn buries the real change inside noise a reviewer still has to read

Mixing a rename, a reformat and a bug fix into one pull request means a reviewer has to untangle all three before they can judge any of them.

Think of returning a borrowed book with every single page re-highlighted in a different color, alongside the one typo you actually fixed. The friend now has to flip through the whole book to find what you changed. They cannot just check the one page.

In plain words: a pull request is a proposal to merge a branch into another, with a diff, a description and a review discussion -- and formatting churn is any part of that diff that alters layout but not behaviour (whitespace, quote style, line wrapping), which adds review cost without adding value, so a checker can flag a hunk as formatting-only when its added and removed text are nearly identical once whitespace is ignored.

A worked example. The bloated branch's reformat of an unrelated router module accounts for 34 of its 51 changed lines -- two thirds of the entire diff is formatting churn on a file that has nothing to do with the stated bug fix. The checker flags this as formatting_churn, flags the leftover debug print() statement as debug_leftover, and also raises undocumented_api -- which turns out to be a false alarm, since the renamed function (pick to select_tool) isn't actually new, just renamed; the checker can tell the diff looks like a new function, but not that it's the same one under a different name.

The key lines. From code/mini-pr/prcheck.py:

# from code/mini-pr/prcheck.py
def formatting_only(h, threshold=0.9, min_lines=3):
    """A hunk whose removed and added text have (nearly) the same tokens once whitespace and quote style are ignored.
    Version 1 required exact equality and missed a reformat that also renamed one function; the threshold fixes that."""
    if not h.added or not h.removed or len(h.added) + len(h.removed) < min_lines:
        return False
    return SequenceMatcher(None, _tokens(h.removed), _tokens(h.added), autojunk=False).ratio() >= threshold

Read it as: the docstring records its own earlier failure. Version 1 demanded the tokens match exactly. That missed a hunk that reformatted and renamed at the same time, since the rename changes one token. Loosening to a 90%-similarity threshold catches "mostly the same tokens, rearranged." It does this without needing a rule for every specific kind of cosmetic change.

Pull request, formatting churn

A pull request is a proposal to merge a branch into another, with a diff, a description and a review discussion. Formatting churn is changes that alter layout but not behaviour (whitespace, quote style, line wrapping), which add review cost without adding value.

Example: a pull request where two thirds of the diff is formatting churn is, from a reviewer's side, almost the same cost as reviewing two separate pull requests bundled badly into one -- which is exactly why "one concern per pull request" is the rule this finding supports.