Reducing cognitive load is perhaps one of the most important things we do, both for our co-workers and for our customers.

What is cognitive load? Simply put, cognitive load is the effort being used in the working memory. This working memory can be overwhelmed when processing large amounts of new or complex information, leading to reduced comprehension and retention.

It would be hard to show this better than was done by Artem Zakirullin at github.com/zakirullin/cognitive-load

When I review pull requests, effort taken to reduce cognitive load for a future reader is one of my primary targets. If your pull request description is so unclear that a person has to read the code to understand it, you aren’t helping your coworkers (who will end up maintaining it) or your customers, who are impacted by the speed and accuracy of the cognition of your work.

If the person who has to maintain or interact with your code later has to spend almost as much time understanding it as you did writing it, then what you did has very limited, and arguably negative value.

So how do we reduce cognitive load?

Our goal should always be to reduce cognitive load for the reader, allowing them to make use of the primary knowledge without having to go through the entire learning process on their own. You found the way up this mountain, leave a clear trail to make the process easier for the person behind you.

1. Remove noise – Don’t ask someone else to expend effort to identify what is important.

What you submit for review should be focused and high quality. Remove any:

• inactive pieces of code
• junk or obviously wrong values
• personal notes or obtuse comments that would confuse someone from outside

A code reviewer should never be required to identity and discard pieces of unused code that aren’t applicable to what they are reviewing.

2. Describe the change clearly. Make clear to the reader What changed and Why, as the How should visible in the code itself.

Speak only to the change and how it works. Don’t include references to other efforts unless they are necessary to the topic, and never, ever refer offhand to something only a person with current context will understand. You’d be surprised how fast context degrades even in closed, tight teams.

3. A pull request ready for review should have all commit messages squashed down to a clear definition of the changes. Under no circumstances should a PR contain commit messages speaking to the progress of the development.

There’s a tremendous load put on the reader by seeing dozens of commits that go back and forth on minor changes. Squash your development process down to make it easier for the reviewer.