# The Critical Difference Between Code Comments and Pull Request Descriptions Microsoft veteran Raymond Chen explains when to use each for effective code maintenance. - **Source:** [www.theregister.com - Articles](https://brifing.si/source/2c34ea50-d341-4a10-925d-12c012a9ad10) - **Published:** 2026-08-16 - **Topic:** [Software & Engineering](https://brifing.si/c/engineering) - **Original article:** - **On Brifing:** https://brifing.si/s/d581ab46-da06-4b75-8838-819a54314b54 ## Purpose of PR Descriptions Microsoft veteran engineer Raymond Chen emphasizes that pull request (PR) descriptions serve as persuasive tools during code review. They contain point-in-time explanations about why a change is needed and how it works. Chen argues these descriptions should be concise texts aimed at convincing reviewers. With the rise of AI-generated PRs, this distinction becomes even more crucial for maintaining code quality across teams and over time. ## Permanence of Code Comments Unlike PRs, embedded code comments carry long-term knowledge. They document function usage, prerequisites, or complex algorithm logic for future developers. Chen states comments 'should speak to someone reading this code 20 years later.' The article cites examples from 1990s-era C++ codebases containing apology comments for spaghetti code - proving some comments outlive their original context by decades. ## The AI-Generated Comment Crisis Comments in AI-generated code sometimes appear nonsensical or misleading. Chen implies developers must rigorously verify these. At the other extreme are teams who claim their 'self-documenting code' needs no comments. Ironically, even brutally honest comments like 'I wrote this but have no idea how it works' now hold value. This highlights the ongoing debate about appropriate comment density in modern codebases. ## Format Wars: Tabs vs Spaces Another perennial debate involves indentation styles. Microsoft's Larry Osterman advocated spaces over tabs in 2024 for consistency. Chen takes a more flexible stance: 'I don't care how you format code, but major style changes deserve separate commits.' This prevents stylistic changes from obscuring functional modifications during code review - a practice becoming essential as AI generates more boilerplate code. ## The Undervalued Commit Message The piece highlights how commit messages preserve change context - acting as historical documents explaining 'why' behind modifications. Chen suggests treating each commit like a mini-PR. Well-crafted messages become particularly valuable during large refactors or when revisiting code years later. This becomes more critical as distributed teams collaborate across timezones and code ownership changes frequently. ## Documentation Culture Spectrum Teams exhibit wildly different commenting habits. Some overwrite (even apologetic) comments while others champion 'self-documenting code.' Chen's pragmatic approach: comments should explain the 'why' - especially traps, known issues, or temporary fixes. This culture proves vital in open source projects where maintainers change frequently. The right balance reduces cognitive load without creating documentation debt. ## Historical Examples from Microsoft The article shares amusing comment examples from Microsoft's 1990s codebases. One engineer wrote pages apologizing for tangled C++ code weaving through module mazes. Another team adopted strictly no-comment policies. Chen recommends middle ground: 'Enough comments to explain why, but no redundant play-by-play.' These historical cases demonstrate how documentation styles reflect their era's programming philosophies. ## Developer Communication as Craft Chen's analysis reveals software development as fundamentally social. PR descriptions (current team), code comments (future maintainers), and commit messages (historical context) form distinct communication channels. With AI-generated code increasing, their proper use grows more critical. Ultimately, well-documented code significantly reduces long-term maintenance costs - proving documentation isn't overhead, but time-saving investment. ## Sources covering this story - https://www.theregister.com/offbeat/2026/08/16/the-what-why-and-how-of-pull-requests-and-source-comments/5287914 — --- _Summary written by Brifing from the original reporting. Copyright in the original article belongs to its publisher; read the full piece at the link above._