How to Unblock Yourself and Increase Your Software Deliverable Velocity

Do you struggle to push project forward because of long code review process?

Photo by Lode Lagrainge on Unsplash

We often think that engineers who cannot deliver are caused by laziness. 

That is often not the case. 

As an engineer, we all worked hard to try to deliver our tasks. However, circumstances and timing are against us and pulling us away from reaching our velocity delivery.

There is one pain point in decreasing software deliverable velocity - blockers. A blocker often occurs when your task relies on other engineers/departments and blocks you from moving forward. 

This blocker has hurt software engineers’ performance reviews, many of whom got into the Performance Improvement Plan (PIP) because this blocker indicates that they cannot push the project forward to deliver business value. 

Aside from blockers caused by external third-party dependency, such as waiting for the solution engineer from company X to provide API documentation, a major blocker that engineers account for in their daily tasks/stories is PR reviews. A PR that hasn’t been approved for days can be counted as a blocker. However, a PR review is a little bit tricky. Many engineers think that it is not their responsibility to speed up the PR review to get their code approved. Still, every single engineer is responsible for unblocking themselves. They are accountable for not being able to deliver because their PR hasn’t been approved. 

Software engineers spend too long on code reviews and have trouble with deliverables because they cannot produce good-quality code. Does that mean we have to time-boxed the time of the code review cycle and decrease the quality of our software?

No. 

Code review is the most important process in producing high-quality software. Good software teams usually have a good code review process. Every single line of code you merge into the main branch means that the entire team agrees that the code is ready to ship to production. If your team has a robust code review process, you should keep adopting it.

Most long-running PR is caused by either a miscommunication in the product/task assumption between engineers or reviewers taking too long to review. I’ve experienced both situations and learned from feedback and mentors how to unblock myself from a long/slow code review process.

Here are some tips to unblock yourself from long code reviews as a software engineer to increase the speed of your deliverables.

Write your Documentation First

Documentation is boring. Engineers hate writing documentation because they think it is a bunch of boilerplate that they need to do for software development rituals. Thus, they push the most boring part at the end of their task.

Instead of writing documentation and code comments at the end of the software development cycle, you should write the documentation and code comments before you even implement your changes.

If you want to speed up your code review process, imprint your thoughts in documentation as much as possible.

Why?

Writing documentation helps you think about the problem and solutions thoroughly. You want to be certain that the documentation you are writing will work. Thus, you take the due diligence to create a proof of concept to ensure that what you wrote is correct.

Moreover, putting documentation at the beginning of the process helps you streamline what they may expect from all of your stakeholders. It saves you much time later when you ask them to look at your PR for approval.

I usually will implement a proof of concept before writing documentation - mentioning the problems I am trying to solve, the approaches, the pros and cons, and the execution strategy. I published that documentation to a channel that involved all stakeholders. During this process, I will get initial feedback from stakeholders and the team on any changes or considerations I should account for. Sometimes it is minor changes where I can update the documentation right away. We often discuss design choices and hop on a call to brainstorm alternative solutions. I realized this helped speed up my review process by avoiding any disagreements and surprises at the later stage of the project.

Try flipping your software development cycle by putting all your thoughts in the documentation before writing any code. You will see your code review get much faster because you have clarified all surprises before you start coding.

Publishing PR As Early As Possible

Submitting your PR is not the end of the development cycle. It is the beginning. 

Many engineers will finish writing their features, create a unit test and test their features, integrate them, and then create a PR. Then, they suddenly realized that they had received 100+ comments in the PR that told them to change every code in that feature.

Publish the core feature of your tasks for feedback. Then, once you and your team agree on the changes, you can perfect the code structure and create test cases to increase the reliability of your code. You want to get your feedback as early as possible so you don’t have to waste precious time perfecting something that will be tossed away.

I usually submit an initial Draft PR for feedback to avoid wasting time making my code beautiful and well-tested. The draft feature in GitHub is very useful for collaborating with team members to get on the same page regarding the implementation details because reviewers understand your thought process by looking at the code.

Break your features into smaller PR

No one wants to review a code that touches 100+ files. 

How are they supposed to review 1000 lines in breaks between their other work? 

I saw reviewers often just push the reviewing task away because they are frightened by the number of file changes.

Everyone has their priorities, and asking for someone to review your PR is a favor rather than a requirement. Therefore, you should respect their time by breaking your changes into smaller features and PR.

If you have to have a big PR, schedule a meeting with the reviewers to walk through the code and explain why it has to be done in a single giant PR.

Try to limit your PR to not more than ten file changes. Other developers will be more willing to review your PR. Make sure your PR has a great description, such as “What is wrong? What are you changing, and how does that fix it? How did you test your change, and what steps does the reviewer need to take t perfectly replicate what you did?” To make the user experience of reviewing PR as great as possible.

It will increase the odds of getting your PR reviewed and approved so you can move on to the next subtask of your feature.

Don’t Over Argue with Your Peers about a single line of code

Although I agree that PR review should be about functionality and ensuring proper implementation, some engineers love to comment on their opinion and nitpick about style preferences.

They think style preference is more like religion. They think using a higher-order function is much better than an if-else and can give you ten different reasons to change your code into a higher-order function. They will correct grammatical errors in your code comments and nitpick on every word you wrote in your PR. In many of these scenarios, you can argue why your code is much better than theirs, or you can follow their suggestion and make changes to your code.

In this scenario, there is no right or wrong approach. Choose your battles.

You can push back by arguing every single comment that you’re reviewer nitpick on. However, this can also slow down your project delivery timeline. To increase the speed of your deliverables, sometimes the best option is to take in the suggestions and move on.

If you received comments about an opinion on the variable name or looping through an element using a map instead of a for-loop, you can simply take in their suggestions if it doesn’t increase the scope.

Your mindset in pushing back on PR comments is, “Whether my comments are helpful to increase the quality of the code and my deliver speed?” 

Look at the overall big picture during the PR comments, and see if it is worth wasting your time by going back and forth with a colleague on what is a good variable name to have.

Conclusion

The key to making your delivery process as fast as possible is to tell the team what you will do before you do it. Writing documentation early in the process helps you share a common understanding of the problem and approaches with all the stakeholders. Once you have a common agreement with the execution strategy, push that draft PR on the core functionality to gather earlier feedback from others.

Remember that a huge PR will result in a long review process. To move your project faster, you should try to publish as minimal PR changes as possible and more frequently. Lastly, if there are any disagreements with PR comments about small style preferences, decide whether or not to push back based on the scope of the work. If it doesn’t change much of your development time and effort, it is better to assent to their comments and move on.

Learning how to unblock yourself and speed up your delivery process is part of science and art. It is based on experience and judgment call whether or not you should push back. Hopefully, with some of these tips, you will be able to unblock yourself, increase your delivery velocity, and make a greater impact on the company.

With that said, it’s over to you. Which other method or tips that you find very useful in unblocking yourself?