| 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. |
I've done this before in production code. One of my only exceptions to my policy against leaving in commented-out code has been things liking leaving the unoptimized serial code commented out at the top of a section of some hand-vectorized code full of SIMD intrinsic. It clearly showed the intended "what", but was also useful to keep around as a baseline for performance testing and reference code to compare against for debugging.