Making patches easy to review

One of the big things that seems to cause a learning curve for many new contributors for Linux and other projects that make a big effort with code review is the process of putting patches together in a way that makes the code review process more smoothly. This is a fairly straightforward thing but it takes a bit of getting used to for people who aren’t used to the idea of patches and commits as a means of communication rather than just a mechanical thing you do to get changes into the codebase. In cases I’ve seen the difficulty . I’m mostly going to talk about this in the Linux context where patches are reviewed by e-mail but the same ideas apply if you’re using a tool like gerrit to do the reviews; it’s also mostly focused on detailed review rather than design level review.

The basic idea is fairly simple – the goal is to make it as easy as possible for someone to read and understand the change that’s being made.

• Make sure the code matches the coding style of the code being modified.
• Make patches as small and self contained as possible – having many patches is much easier than having complicated patches.
• Provide a changelog clearly describing everything that’s going on in the patch.

The result here should be something that’s easy for people to review. Keeping in line with the coding style is just a generally good idea for code legibility which is obviously a key thing for people reading the code to review it. Having a clear description of the change means that the reviewer knows what the patch is supposed to do and can verify that the patch does that rather than having to spend effort figuring out if whatever the code is doing is intentional. Making changes small and simple makes them much easier to think about – the idea itself is easier to keep in your head and there’s fewer things to check so the process of validating things is easier.

It’s not just about making life easier for reviewers. The process of making simple changes and describing them clearly can be really helpful for spotting issues when writing code; it forces you to think through what’s being done much more clearly than might happen otherwise. There’s also an ongoing benefit to anyone working with the code in the future. Since each change ends up including at least some explanation of what the code is supposed to do and since revision control systems generally have some equivalent of git annotate it’s usually reasonably straightforward to find the changes that introduced the code that you’re looking at. Small changes with good changelog entries mean it’s much more likely that the changelog will provide a useful explanation as to what the author was thinking and explain why the code is the way that it is. It’s much harder for documentation to go missing from the SCM than it is for it to go missing elsewhere, and it’s much more likely that documentation in the commit is going to be up to date than external documentation, especially prewritten design documentation.

In the context of large scale reviews the usual technique is to combine reviews of individual changes with a read through of the final code after all the individual changes have been applied. Often the build up of the code through incremental changes is a enough to show the overall design but a read through of the final code can be helpful in allowing people to understand where things are going.