The same can of course apply to code: there's many instances where someone will assume they understand a tricky bit of code because they read a well written comment. That's a bad sign, as the code probably had a lot more nuance that was not covered by the commenter. And then did they properly understand what the comment is saying ? we now have a two level readability problem.
In general, I sympsthize with the approach that making it easier for people to understand shouldn't happen in comments. It's frustrating for the people reading the code, but we're paid professionals, and frustration is better to me than lack of understanding or glossing over the actual behavior (I'd trade less bugs for hurt feelings any day)
Comments should bring additional info that complements the code in a meta way (link to bug reports, design documents, discussion threads etc.)
https://bigthink.com/the-present/want-less-car-accidents-get...
The same can of course apply to code: there's many instances where someone will assume they understand a tricky bit of code because they read a well written comment. That's a bad sign, as the code probably had a lot more nuance that was not covered by the commenter. And then did they properly understand what the comment is saying ? we now have a two level readability problem.
In general, I sympsthize with the approach that making it easier for people to understand shouldn't happen in comments. It's frustrating for the people reading the code, but we're paid professionals, and frustration is better to me than lack of understanding or glossing over the actual behavior (I'd trade less bugs for hurt feelings any day)
Comments should bring additional info that complements the code in a meta way (link to bug reports, design documents, discussion threads etc.)