Code reviews are important. They are a great way to make sure your codebase stays clean and maintainable. If you use Github, you are probably already using pull requests as part of your code review process. The process of documenting pull requests going into a codebase can sometimes become tedious, or be treated as an after thought. It’s bad news for your organization because poorly written pull requests can contribute to complacency when merging new code. Often, the submitter claims to not have time to properly describe the problem they are fixing, and in turn, the reviewer does not have time to figure out the poorly explained changes. Under the pressure of a deadline, a reviewer may simply accept the changes as-is in order to forgo the time cost of sitting down and talking it through. Writing a good explanation takes time, but how do you find a balance between brevity and acknowledging that you have deadlines to meet?##What makes a good pull request?
A habit I have picked up when creating pull requests is the “Why/What Changed” format. It’s great for a variety of reasons.
- It doesn’t waste your time by forcing you to write lengthy explanations.
- It doesn’t degrade the quality of your internal code review process.
- It gives the reviewer an incentive to actually review your code (instead of staring at it).
- Non-technical stakeholders can read your pull requests and still figure out what’s going on.
HEADING I: Why?
Make a simple bulleted list of what caused you to write the code in the first place. Was it because of a recent bug? Was it the result of a client request? What problem existed prior to this pull request? Give the reviewer a frame of reference.
- “This pull request is to fix that slow SQL query that was bogging down the production machine last week.”
- “This pull request implements a new blog editing feature requested by the client.”
HEADING II: What Changed?
Take a look at the list of files changed and give the reviewer your reasoning for it. Just one sentence per file is usually enough. I usually make a bulleted list for these items with Github Flavored Markdown.
- “Streamlined the signup process by removing the modal dialog”
- “Added a
middle_namefield to the
Most of the time, that’s all you need to get your point across and give your code reviewer the information they need. Medium and large sized teams live in an environment where no one person can know the domain of their software. Do your team members a favor, write a pull request that is concise and informative.