I disagree. Function names should describe, as clearly and as precisely as possible, what they do rather than why they do it in one particular way.
I find comments helpful when the implementation of a function is surprising, i.e. it diverges from patterns one might normally expect for similar tasks. Specialized performance optimizations would be one example I can think of.
ADRs are useful, but I’m not sure they make much sense for implementation details at the level of a function.
All that said, I do agree that functions should be clear in name and content and I think comments should be rare.
I disagree. Function names should describe, as clearly and as precisely as possible, what they do rather than why they do it in one particular way.
I find comments helpful when the implementation of a function is surprising, i.e. it diverges from patterns one might normally expect for similar tasks. Specialized performance optimizations would be one example I can think of.
ADRs are useful, but I’m not sure they make much sense for implementation details at the level of a function.
All that said, I do agree that functions should be clear in name and content and I think comments should be rare.