The most valuable comments I find in any given codebase look like this: Hack! This thing is weird because of this and that reason. I tried to implement a more elegant solution, but due to X and Y constraints, I failed. Hack! This is weird because there is a bug in library X that we depend on. See https://github.com/library/issues/420 Note! I tried options A, B, and C and decided to do this weird thing because, while it looks wrong, it turned out to be the best solution at the time of writing. These comments do not explain what the code does. They explain why the code looks the way it does. They bring into light historical context, failed attempts, and external constraints that are otherwise invisible. We all occasionally fail to communicate our intent to the next developer. That is normal and unavoidable. What matters is leaving a clear mark when something non-obvious or hacky is done on purpose. Increasingly, the “next developer” is a metal-headed clanker: an LLM. ...
Notes about what I do