Granularity Of Code Changes

A few rules about granularity of changes I wrote a long time ago in response to a question on the EGit mailing list.

These were copied verbatim into the EGit Contributor Guide.

Granularity of Changes

• Make small commits, as small as reasonable. This makes them easy to review.
• Each commit should have a commit message that explains very clearly what the commit sets out to achieve (unless this is abundantly clear from the code itself, which is basically only the case for trivial patches). Also, when you fix a bug then report which bug you fix. When there are deeper reasons for doing things the way the commit does, then explain these as well. This all is for the reviewers and yourself: the context of the commit is completely clear.
• Do not mix concerns in commits: have a commit do a single thing. This makes them reviewable 'in isolation'. The purpose of the commit is clear and can be understood easily by the reviewers and yourself.
• Do not break the build and tests for any commit: this is very important for bug hunting.
• Split your work into multiple smaller pieces of work (when possible) and implement each of these pieces in a series of commits.
• A series of commits should work towards a 'feature' in a clear way and only 'enable' the feature in the last commit of the series.
• In a series of commits first lay the groundwork and then build on that towards the feature.