Microsoft veteran explains why pull request descriptions differ from code comments

Raymond Chen, a veteran Microsoft engineer known for his long-running blog The Old New Thing, recently published a post clarifying the distinct purposes of pull request descriptions and comments embedded in source code. His guidance arrives amid a surge in AI-generated code and pull requests, where the quality of annotations has become a topic of debate among developers.

Chen explained that a pull request description is a point-in-time statement aimed at persuading approvers to accept a proposed change. It is essentially an exercise in persuasive writing, providing context relevant to the code review itself. In contrast, comments in the code are durable information meant to help future programmers understand how to use functions correctly, including prerequisites and other details that remain useful long after the pull request is merged.

This distinction is particularly timely given the increasing volume of pull requests produced by AI coding tools, which sometimes include unusual or unhelpful annotations. Chen's advice echoes broader discussions about code quality and maintainability, including the perennial debate over tabs versus spaces. In 2024, another Microsoft veteran, Larry Osterman, took a middle-ground stance, noting that tabs were practical when storage was limited but that spaces now offer consistency. Chen himself has said he does not care how developers format their code, but he recommends making any wholesale formatting changes as a separate check-in to avoid overwhelming maintainers with massive diffs.

The underlying theme is that clear communication in software development is essential, whether through persuasive pull request descriptions or informative code comments. Chen's post serves as a reminder that both elements play complementary roles in the collaborative process of code review and maintenance.