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:
- Add a
- Add a controller for performing CRUD on
routes.rbto include paths for
- Update user policies to ensure only admins can delete
- Add tests for policy changes
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.
Simpler words win if you’re trying to quickly convey meaning, and normal words are preferable to jargon. Here are a few examples:
use. They have different meanings, and you’re likely wanting the meaning of
use, which has the added bonus of being fewer characters.
request. “The ask here is to replace widget A with widget B.” Ask is not a noun; it’s a verb.
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.
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
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.
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.
Loved the article? Hated it? Didn’t even read it?
We’d love to hear from you.