Comments in the code vs PR description

When crafting a pull request (PR), there are two key locations to provide context and justification for your changes: the PR description and the code itself. Each serves a distinct purpose.

The PR description is the primary place to communicate why your change should be accepted. In the title, you outline the problem you're addressing or the feature you're introducing. A concise title helps reviewers quickly identify relevant changes. Within the description, you delve into the specifics, explaining the root cause of the issue or the new functionality you're adding.

You can also discuss alternative approaches you considered and the reasons you opted for your chosen solution. This section often includes supplementary material like screenshots demonstrating the problem's resolution or confirming the completion of associated paperwork, such as unit tests.

On the other hand, code comments are intended to clarify aspects of the code itself. These comments should answer questions like how to properly invoke a function, any prerequisites it may require, or best practices for usage. The information conveyed through code comments should remain accurate and relevant even after the PR has been approved and merged.

For instance, if you've verified that a specific caller of a function passes the correct flag, highlighting this fact in a code comment ensures the reviewer is aware of this validation, preventing potential future issues if other callers make the same mistake.

In summary, the PR description serves to justify the overall change and its benefits, while code comments focus on explaining the code's functionality and usage to ensure clarity for both current reviewers and future developers who may interact with the code.