Yeah when I find myself wanting to write a comment that describes the implementation, I usually end up writing a test where possible. I'm trying to think, but

Yeah when I find myself wanting to write a comment that describes the implementation, I usually end up writing a test where possible. I'm trying to think, but I can't come up with any kind of comment that has been useful that didn't have a "because" word, explicitly or implied. Like, even if there's a comment like: "This function only queries X and Y fields. Don't add more. If you need more than that, use this_other_function instead." It has an implied reason behind it, and the mistake is not adding that reason to the comment. So this comment would be missing something like "[...] because this is being used in a critical part of the code that is very nitpicky and it's very difficult to test because requires some annoying manual steps", or something like that. There are probably situations where a "what" or "how" comment really are better than "self-documenting code" though. I would probably appreciate those comments if I ever need to read branchless code, SIMD code, or similar performance-sensitve witchcraft.