An all-too-familiar scenario: you open a pull request in github. It has no description. It has three commits: "WIP," "Fixes issue," and "Whoops formatting." It has 24 file changes littered around the codebase. Your coworker opens your PR for review and promptly closes their browser window. Why? Your pull request did not communicate the motivation, reasoning, and proposed execution of your change. It's a difficult proposition even in good conditions.
We can do better for ourselves and our fellow developers. Here are some strategies we use to make the intention of our own pull requests simpler to understand and their proposed changes easier to review:
Tale Telling
This will not be the first post to highlight how good a good commit message is. There's more we can do beyond a pithy description of a coherent unit of work. Commits can be made to tell a story in context from one to another: clearing the ground here; then, establishing the new system there; then, exercising the change in this path; finally, whoops, formatting. Rebase (-i) is a cantankerous but invaluable friend.
Illustration
Changes to a user interface can be described visually with a set of images, a gif, or a short voiceover walkthrough which focuses on the new experience. Show, don't tell, can be taken literally to great effect.
Exercise
We execute the code we're authoring in order to make sure it works, right? (Right?) A living system is usually more than the automated tests that we also include. Record your setup, and interaction, and outcome. Flip back and forth between your console/UI, the code, the database. Show how everything breathes together.
Finally, include a gif of a cute Koala at the end of your well-written description. Because diligent reviewers deserve a small treat.