[kwhitefoot]

> writes comments that explain why the code isn't written in another way."

Exactly! I have written code that required comments five times as long as the code itself to defend the code against well meaning refactoring by people who did not understand the code, the domain, or the care needed to handle large dynamic ranges.

I have also written substantial functions with no comments at all because it was possible and practical to name the function and all the variables so that the meaning was clear.

[yxhuvud]

I've also written that kind of comments, and then promptly had it refactored by people not reading comments.

[klyrs]

It's true! If you come across a well-documented and complex piece of code, it's always easier to delete it all and write a simpler (and less correct) replacement than reading all of that code and documentation. And since your replacement is simpler, you're free to delete the inapplicable documentation that you saved so much time not reading!

If you didn't back that documentation up with some tests to reflect the necessity of that complexity, this is an avoidable tragedy. But if the junior then comes in and deletes your tests because they don't pass, that's a firin'.

[kwhitefoot]

In the end we had sufficiently good tests to detect such foolishness. But even that isn't good enough because if the result of the test is merely slightly off some people will just adjust the assertions!