The comment in PR anti-pattern
Senior Engineer at Spotify. I write mostly short posts where I share my thoughts regarding topics that happen to catch my attention at any given time. Topics related to programming, technology, lifestyle, and self-improvement. When I am not working, I am probably busy being the best father I can be. Opinions expressed are solely my own and do not express the views or opinions of my employer.
I have seen a pattern where PR authors add context around a piece of code in a Pull Request rather than in-line in the code. They intend to convey context to the reviewer. However, that context gets lost as soon as that code is merged.
This is unfortunate. Both future maintainers and AI agents would have benefited from that context.
It is much better to add that context directly to the code via comments. In some communities, comments tend to get a bad reputation. The general argument against them is that code should already be self-explanatory. I disagree. A good comment explains the why rather than the how.
The code I enjoy reading is from developers who take the time to explain the context around a change. Ghostty is a great example of a project where each file is thoroughly commented with useful context.
This makes the code fun to read, and the project fun to collaborate on.
