What is the most effective way to explain code in a code review using a pull request?

Question

I work for a small company with only three programmers (including myself).

Our workflow is:

1. We write the code;
2. We create a pull request on Github;
3. We ask for code review;
4. We merge the pull request.

Normally when I want to explain the motivation behind that code, I review my own code in my pull request and add comments to explain each part. The problem with this approach is that is uncomfortable to review code with many comments and the comments can be out of order depending on the order of the files.

I also tried describing my solution in the pull request description; the problem with this approach is that the reviewer would need to keep going back and forth to the description and code to understand what's happening (and also the files can be out of order).

With that being said: is there any better alternatives to explain code that is going to be reviewed in a pull request? I feel like none of my solutions are really effective.

Answer 1

There are a few options.

One option is to utilize GitHub issues and ensure that every PR is associated with an issue. This gives you the opportunity to prioritize work, a singular place to talk about the problem and potential solutions, collate information related to the problem and the design, and easily link the issue to the pull request.

Another option is to use the pull request description, as you describe. You can give a high-level overview of the solution that you have chosen to implement.

If there are particular things that you like to comment on, self-commenting can also be used to make additional notes.

These three options aren't mutually exclusive. In fact, you can use all three in the same pull request without much issue. However, if you're still getting pushback on the pull requests, I'd wonder if there's insufficient alignment on the problem and possible solutions before the code is written or if the design and code are simply too difficult to understand. In these cases, focusing on the pull request won't solve the underlying problems.

I will say that the problem of ordering the files in the pull request to be logical is one that I've encountered. To the best of my knowledge, there's no good solution for this, other than using the pull request description to give an outline of how to best read the pull request.