Writing on his blog The Old New Thing, Microsoft engineer Raymond Chen has spelled out the difference between a pull request description and comments embedded in source code. The PR description, he says, is a point-in-time statement that serves the code review itself. It is an exercise in persuasive writing, because its job is to convince the approver that the change should be accepted.

Comments in the code play a different role. They explain the code itself: how a function should be called, which prerequisites apply, and similar knowledge. Chen calls this information durable, since it stays useful long after the pull request has been merged.

The Register adds that commit messages arguably deserve a place in the discussion too. The topic lands at a moment when AI coding tools are generating large volumes of pull requests, along with annotations of occasionally questionable quality. The piece recalls older extremes of the commenting culture, from a colleague whose C++ commentary consisted mainly of apologies to future maintainers, to another who refused to write any comments at all on the grounds that the code was self-commenting. A more honest modern annotation, the author suggests, might read: written by some coding assistant, and nobody knows how it works.

The article also connects the debate to the perennial tabs-versus-spaces dispute. In 2024, fellow Microsoft veteran Larry Osterman took the position that tabs made sense when storage was scarce, but spaces are the safer choice today because they always work and stay consistent. Chen's own stated view on formatting is more libertarian: he does not care how anyone formats their source code. His one practical suggestion is to commit any wholesale reformatting separately, so reviewers are not buried under a diff dominated by style-guide changes.

The closing point returns to Chen's core distinction: the PR description argues why a change deserves acceptance, while code comments preserve what future programmers need in order to understand the code.