alt Hacker News> 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:
Replies
switchbak • today at 5:30 PM
Documenting it in a way that ensures it satisfies the example case would be preferred. You know, like with a test.
This isn't a counterpoint, it's just additional (and barely relevant) information.