The what, why, and how of pull requests and source comments

Veteran Microsoft engineer Raymond Chen recently clarified the distinction between pull request descriptions and comments embedded within code. Both are essential, but they serve distinct purposes.

According to Chen, the PR description is a snapshot of information relevant to the code review process at a particular moment. It is a persuasive document aimed at convincing the approver that the proposed changes should be accepted. In contrast, code comments are meant to elucidate the code itself. These comments provide enduring insights that remain valuable even after a pull request has been finalized.

Chen argues that commit messages should be considered alongside PR descriptions and code comments, though the focus presently lies on the difference between PR descriptions and code comments, given the surge in AI-generated pull requests and sometimes puzzling annotations. Interestingly, developers from Chen's past, like another colleague who avoided commenting altogether, had a different approach.

They believed their code was self-explanatory. Today, a more candid comment might read: "This was written by [name], and I have no idea how it works."

This situation mirrors another ongoing debate among developers: whether to use tabs or spaces for indentation. In 2024, Microsoft veteran Larry Osterman adopted a neutral stance, suggesting that tabs were acceptable when storage was limited, but spaces were preferable due to their consistent and reliable nature.

Chen's perspective on code formatting is flexible: he doesn't care how code is formatted as long as it remains his own source code. However, he recommends treating any significant changes in formatting as a separate commit, so maintainers aren't overwhelmed with a diff dominated by a new style guide.

Ultimately, Chen's distinction between PR descriptions and code comments highlights their different roles: PR descriptions explain why a change should be accepted, while code comments preserve the necessary context for future programmers to understand the code.