Chen on Code Comments: A Clearer Picture for Approvers
Veteran Microsoft engineer Raymond Chen has highlighted the importance of understanding the difference between pull request descriptions and comments embedded in code.
According to Chen, a pull request description is a point-in-time statement that provides information relevant to the code review process. It's an exercise in persuasive writing, aimed at convincing approvers to accept a change.
On the other hand, comments in the code are for discussing the code itself, including explanations of how it works and any prerequisites. This information remains useful even after the pull request is completed.
Chen's distinction comes as AI coding tools generate an increasing number of pull requests with varying levels of quality, including sometimes 'interesting' annotations.