How do you write a good code review request?

Giving some context is helpful but if the code review request requires extensive explanations you should ask yourself critically if your code itself lacks clarity and structural coherence. Good code should be pretty much self-explanatory for a sufficiently competent reviewer. Ideally, the code reviewer should also be a person in your organization who is familiar with the context of your code.

1. A brief description of what the pull request aims at, is a must for a good first impression from any reviewer. 2. I list the test cases covered, also as part of the code review description so reviewers don't have to spend time trying to verify if all required test cases are covered. 3. Self-review, even before tagging any reviewers, is very much recommended. 4. Being proactive in adding comments on specific lines of code that involves any heavy logic explaining why that line of code needed an update, is considered a good practice too. 5. For any refactoring of the code done to remove any unused variables, methods, imports, test stubs etc., adding a file level comment that the removed code is intentional, helps.

Explain the purpose of the changes: - Clearly state why the change was made and what it addresses. - Link it to the relevant task, ticket, or feature for easy traceability. Attach supporting documentation: - Include design documents, RFCs, or any references that provide context and reasoning behind the implementation. Detail the testing process: - List the test cases executed, covering both positive and negative scenarios. - Specify the environments where testing occurred (e.g., local, staging, production). - Attach evidence such as logs, screenshots, or test reports to validate the results.

Including the details is important but don’t overload your reviewers with them. Work to create a succinct summary to start off with and then allow them to dig deeper if they need or want to.

Provide Context for Changes: Offer a brief explanation of the reasons behind each change. Example: We modified the data retrieval method in the lending platform to enhance performance by leveraging asynchronous requests. This change was necessary to meet the required response time for processing loan applications. Highlight Significant Modifications: Point out significant modifications such as algorithm changes or architectural adjustments. Example: We refactored the authentication module in the legacy system migration project to adopt OAuth2 for improved security and interoperability with third-party services.

Don’t forget to ask for your security related review! Questions you could ask here: - How would someone attack or abuse this code? - If this code fails, how do you think it’ll happen?

Being polite and grateful should be part of and professional mindset and culture of work. It is essential to enable a free and productive exchange of ideas and create space for personal development , facilitate learning and make progress as a team. But at the same time it should be natural to question things and to allow criticism. My advice is: Let people take their time to review code. There should be no pressure to complete code reviews too fast without the necessary concern. Let them talk and actively discuss their code. Let them know: It‘s a draft, nothing else. They should suggest changes and not just accept the code as it is.