SOFTWARE
Microsoft veteran on knowing the difference and convincing approvers to accept a change
Seasoned Microsoft engineer Raymond Chen has shared his insights on distinguishing between pull request descriptions and inline code comments—both essential elements of code review, yet serving distinct roles.
On his The Old New Thing blog, Chen explained: “The PR description is a point-in-time statement, offering context relevant specifically to the code review process. It’s an exercise in persuasive writing—you’re aiming to convince the approver that your change merits acceptance.”
Inline code comments carry a different purpose. “They’re meant to explain the code itself,” Chen noted. “How should this function be called? What are its prerequisites? These details are enduring—they remain valuable even long after the pull request is closed.”
While commit messages also play a role in documentation, the distinction between PR descriptions and code comments takes on renewed relevance amid the surge of code contributions from AI-powered development tools—and the sometimes questionable quality of their accompanying annotations.
Veteran developers may recall earlier days when overly verbose comments dominated legacy systems. One former colleague of this writer’s produced reams of commentary apologizing to future maintainers who would inevitably inherit sprawling C++ codebases. Others took the opposite extreme, leaving functions entirely unannotated under the belief that clean code needed no explanation.
In today’s landscape, a brutally honest annotation might say: “Generated by AI, with zero understanding of how it actually works.”
This debate mirrors other longstanding tensions in software engineering, such as the perennial battle between tabs and spaces for indentation. Larry Osterman, another longtime Microsoft engineer, addressed this in 2024 with a pragmatic stance: “Tabs made sense when memory was scarce, but spaces offer consistency across environments.”
As for Chen, his take on formatting debates remains refreshingly nonchalant: “I don’t care how you format your source code—it’s your code.”
His recommendation? If you’re planning a major reformatting overhaul, isolate it into its own commit so reviewers can focus on actual logic changes rather than being overwhelmed by stylistic noise.
Ultimately, Chen’s guidance boils down to clarity of intent: Pull request descriptions justify why a change deserves approval, while inline comments equip future developers with the knowledge they’ll need to build upon—and maintain—your work. ®
