Rick Carlino

Lead software developer and co-founding member @ Farmbot, Inc.

Co-founder @ Fox.Build Makerspace, St. Charles, IL.

Reddit Twitter GitHub LinkedIn Stack Overflow Email Updates

Universally Awesome Pull Requests

July 25 2014

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.

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.

Examples:

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.

Examples:

Conclusion

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.

(C) 2017 Rick Carlino