[msla]

> Similar to the "code should be self documenting - ergo: We don't write any comments, ever"

My counterpoint: Code can be self-documenting, reality isn't. You can have a perfectly clear method that does something nobody will ever understand unless you have plenty of documentation about why that specific thing needs to be done, and why it can't be simpler. Like having special-casing for DST in Arizona, which no other state seems to need:

https://en.wikipedia.org/wiki/Time_in_the_United_States

[pc86]

This isn't a counterpoint, it's just additional (and barely relevant) information.

[msla]

It's a counterpoint to the maxim, not the post I'm replying to.

[switchbak]

Documenting it in a way that ensures it satisfies the example case would be preferred. You know, like with a test.

[msla]

"Why is this person testing that Arizona does such bizarre things with time? Surely no actual state is like that! Such complexity! Take it out!"