Why Change Lists Should Be Small and How to Keep Them Small

Why CLs Must Be Small

Faster code review: Reviewers can more easily find a 5‑minute slot for a small CL than allocate 30 minutes for a large one.

More thorough review: Large CLs overwhelm reviewers, causing important comments to be missed.

Less likely to introduce bugs: Small CLs are easier to analyze for impact.

Less wasted work if rejected: A huge CL that is rejected wastes far more effort than a small one.

Easier to merge: Large CLs cause more conflicts when other changes land.

Better design decisions: Improving a small CL’s design is simpler than tackling a massive change.

Reduces blocking: An atomic CL lets you continue other work while waiting for review.

Simpler rollback: Smaller CLs involve fewer files, making rollback less complex.

Reviewers may outright reject an oversized CL, asking the author to break it into smaller pieces.

How Small Should a CL Be?

Aim for fewer than 800 lines, preferably under 400, and ideally under 100 lines. Studies show reviewers can handle about 500 lines per hour, with optimal CLs under 400 lines.

Correctly Reducing CL Size

Each CL should address a single, tiny change.

It usually represents a part of a feature, not the whole feature.

Include related test code; if automated tests are not possible, add a TestPlan in the description.

Provide all context needed for reviewers within the CL description.

After merging, the CL must not break the build or production behavior.

Avoid making the CL so small that the code becomes hard to understand; include necessary API usage in the same CL.

There is no hard industry rule for “too large,” but ~100 lines is generally reasonable, while ~1000 lines is usually too big. File count also matters; many small changes across many files can be problematic.

When Are Large CLs Acceptable?

If a file is being deleted, its line count is irrelevant.

Large CLs generated by trusted automated refactoring tools can be acceptable, provided merge and testing requirements are still met.

How to Make CLs Smaller

Split Files

Group files that need different reviewers but are otherwise independent, and submit them in separate CLs while maintaining logical order.

Separate Refactoring from New Features/Fixes

Keep refactoring work in its own CL separate from feature additions or bug fixes; small clean‑up can stay with the feature/fix CL, but large refactors should be isolated.

If You Cannot Reduce the CL Further

Consider adding a preceding refactoring‑only CL to pave the way, discuss with teammates for alternative small CL strategies, or obtain explicit reviewer consent for a large CL while taking extra care to avoid bugs and ensure thorough testing.

Other Considerations

Do Not Break the Build

When CLs depend on each other, ensure the system builds and passes tests after each CL to avoid blocking other developers.

Include Corresponding Test Code

Every CL that changes logic should include new or updated tests; pure refactoring CLs should also have tests, either existing or added, to verify behavior remains unchanged.

Validate new behavior with new test cases.

Ensure critical logic is covered.

Provide confidence for subsequent refactoring.

Refactor test code when needed.

Introduce larger integration tests as appropriate.