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

Microsoft veteran on knowing the difference and convincing approvers to accept a change

Veteran Microsoft engineer Raymond Chen has weighed in on the difference between a pull request description and comments embedded in the code.

Both matter, but they serve very different purposes. As Chen noted on his The Old New Thing dev blog: "The PR description is a point-in-time statement, providing information that is relevant to the code review itself.

"It is an exercise in persuasive writing: You are trying to convince the approver that your change should be accepted."

REG AD

And sticking text in the source? "Comments in the code are for talking about the code itself. What is the correct way to call this function? Does it have specific prerequisites? This information is durable: It is information that remains useful even after the pull request completes."

REG AD

We'd argue that commit messages should be considered as well, but the distinction between PR descriptions and code comments is timely, given the volume of pull requests being generated by AI coding tools alongside some occasionally "interesting" annotations.

Then again, anyone complaining about comments in AI-generated code would be wise to inspect those written decades ago by one of this writer's former colleagues. They consisted of pages apologizing to whichever future programmer had to untangle the spaghetti of C++ lurking through a maze of modules. Another colleague refused to annotate their code at all, insisting it was "self-commenting."

These days, an honest comment might read: "This was written by <insert coding assistant name here>, and I have no idea how the heck any of it works."

It echoes another perennial developer dispute: whether code should be indented with tabs or spaces. In 2024, another Microsoft veteran, Larry Osterman, took a decidedly fence-sitting position: tabs were fine when storage was at a premium, but spaces now make more sense "because it always works and it's always consistent."

Chen's position on tabs versus spaces is not widely known, but his broader opinion on code formatting was straightforward: "I don't care how you format your source code. It's your source code."

He did suggest making any wholesale change in layout or formatting a separate check-in, so maintainers aren't faced with an epic diff dominated by a new style guide.

All of which brings us back to Chen's distinction: the PR description explains why maintainers should accept a change, while comments preserve what future programmers need to understand the code. ®