Writing Tips for Improving Your Pull Requests

You’ve just finished knocking out a complex feature. You’re happy with the state of the code, you’re a bit brain-fried, and the only thing between you and the finish line is creating a pull request.

You’re not going to leave the description field blank, are you?

You’re tired, you want to be done, and can’t people just figure out what you did by looking at the code? I get it.

The impulse to skip the description is strong, but a little effort will go a long way toward making your coworker’s lives easier when they review your code. It’s courteous, and–lucky for you!–it doesn’t have to be hard.

If you’re thinking I’m going to suggest writing a book in the description field, you’re wrong. In fact, I’m going to show you how to purposely write less by using the techniques below.

Make it Scannable

If your code is a report for the board of directors, your pull request description is the executive summary. It should be short and easy to digest while packing in as much important information as possible.

The best way to achieve this combination is to make the text scannable. You can use bold or italic text to draw emphasis to important details in a paragraph. However, the best way to increase scan-ability is the liberal application of bulleted lists. Most of my PR descriptions start like this:

There are a few things to note here. I’m using callouts to bring attention to important changes, including the object that’s being added and important files that are being modified. The sentences are short and digestible. They contain one useful piece of information each. And, for readability, they all start with a capital letter and end with no punctuation. Consistency of formatting makes for easier reading.

Speak Plainly

Simpler words win if you’re trying to quickly convey meaning, and normal words are preferable to jargon. Here are a few examples:

* Replace utilize with use. They have different meanings, and you’re likely wanting the meaning of use, which has the added bonus of being fewer characters.

* Replace ask with request. “The ask here is to replace widget A with widget B.” Ask is not a noun; it’s a verb.

* Replace operationalize with do. A savings of 12 characters and 5 syllables!

There are loads of words that we use daily that could be replaced with something simpler; I bet you can think of a few off the top of your head. For more examples, see my book recommendations at the end of this article.

Avoid Adverbs

Piggybacking on the last suggestion, adverbs can often be dropped to tighten up your prose. Spotting an adverb is easy. Look for words that end in -ly. Really, vastly, quickly, slowly–these are adverbs and they usually can be removed without changing the meaning of your sentence. Here’s an example:

“Replace a really slowly performing ActiveRecord query with a faster raw SQL query”

“Replace a slow ActiveRecord query with a faster raw SQL query”

Since we dropped the adverbs, performing doesn’t work on its own, so we can remove it and save even more characters.

Simplify Your Sentences

Sentences can sometimes end up unnecessarily bloated. Take this example:

“The reason this is marked DO NOT MERGE is because we’re missing the final URL for the SSO login path.”

The reason this is can be shortened to simply this is. The is before because is unnecessary and can be removed. And the last part of the sentence can be rejiggered to be more direct while eliminating an unnecessary prepositional phrase. The end result is succinct:

“This is marked DO NOT MERGE because we’re missing the SSO login path’s production URL.”

Bonus Round: Avoid Passive Voice

Folks tend to slip into passive voice when talking about bad things like bugs or downtime. Uncomfortable things make people want to ensure they’re dodging–or not assigning–blame. I’m not saying you should throw someone under the bus for a bug, but it helps to be direct when writing about your code.

“We were asked to implement the feature that caused this bug by the sales team.”

The trouble here is were asked. This makes the sentence sound weak. Luckily, a rewrite is easy:

“The sales team asked us to implement the feature that caused this bug.”

By moving the subject from the end of the sentence to the beginning, we ditch an unnecessary prepositional phrase by the sales team, shorten the sentence, and the overall meaning is now clear and direct.

There’s More!

But we can’t cover it all here. If you want to dig deeper, I recommend picking up The Elements of Style. It’s a great starting point for improving your writing. Also, Junk English by Ken Smith is a fun guide for spotting and avoiding jargon, and there’s a sequel if you enjoy it.