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

Microsoft veteran Raymond Chen has provided insights into the distinction between pull request descriptions and code comments. Chen explained that pull request descriptions serve as a point-in-time statement, offering crucial information for the code review process. These descriptions are essentially persuasive writing aimed at convincing the approver to accept the proposed change.

In contrast, comments embedded within the code itself are meant for discussing the code itself, such as asking questions like "How do I call this function?" or "What are the specific prerequisites for this function?"

Chen argued that comments in the code are durable information that remains relevant even after a pull request is completed. He also pointed out that commit messages should be considered as part of this durable information, although he noted that the distinction between PR descriptions and code comments is particularly relevant given the increasing number of pull requests generated by AI coding tools and sometimes peculiar annotations.

The debate about code comments is not new, as Chen referenced comments written decades ago by his former colleagues. These comments were lengthy apologies to future programmers tasked with untangling the messy C++ code within a complex web of modules. Another colleague took the opposite approach, refusing to add any annotations to their code, insisting that it was "self-commenting." Today, a more honest comment might read: "This was written by [author], and I have no idea how the heck any of it works."

This debate over code comments echoes another perennial developer dispute: the use of tabs or spaces for indentation. In 2024, Microsoft veteran Larry Osterman took a somewhat neutral stance, suggesting that tabs were acceptable when storage was scarce but spaces were preferable now due to their consistency and reliability. Chen did not publicly state his own opinion on tabs versus spaces, but he did suggest that any major changes in layout or formatting should be handled as a separate check-in so that maintainers are not overwhelmed by a diff dominated by a new style guide.

Ultimately, Chen's stance on code formatting is clear: "I don't care how you format your source code. It's your source code."