Pull request descriptions justify changes while code comments document usage and constraints

The distinction between PR descriptions and code comments lies in their temporal relevance and audience. PR descriptions are persuasive documents aimed at reviewers, explaining the necessity and correctness of a change at the moment it is proposed. They address questions like 'Why is this change needed?' and 'Why was this implementation chosen over alternatives?' This context is ephemeral, once the PR is merged, the justification may no longer be relevant, especially if the codebase evolves. For example, a claim that 'all callers of this function were checked' is only true at the time of review; future changes could invalidate it.

Code comments, by contrast, serve as durable documentation for anyone interacting with the code later. They answer questions like 'What are the prerequisites for calling this function?' or 'What edge cases does this handle?' This information remains useful long after the PR is closed, even if the original author moves on. A comment like 'The JSON schema accepted by this function is documented here' is timeless, it helps future developers use the function correctly, regardless of when they encounter it. Misplacing such details in a PR description buries them in review history, where they are harder to find and maintain.

The cost of conflating these two is twofold. First, transient justifications clutter the codebase, making it harder to read and maintain. A comment like 'The Doodad component will take advantage of polarity reversal' suggests a dependency that may no longer exist, misleading future maintainers. Second, durable documentation gets lost in PR history, forcing engineers to dig through old reviews to understand how the code works. This slows down debugging and refactoring, as critical context is no longer co-located with the code it describes.

Adopting this separation requires discipline but pays off in clarity. PR descriptions should focus on the 'why' and 'how' of the change, including validation steps, rejected alternatives, and screenshots or test results. Code comments should focus on the 'what', how the code behaves, its invariants, and usage guidelines. The boundary is clear: if the information is only relevant to the current change, it belongs in the PR; if it helps future developers understand or use the code, it belongs in a comment. This rule of thumb reduces ambiguity and ensures that each piece of information lives where it is most useful.