Or how would you name methods and variables to explain why some payment reconciliation process skips matching for transactions under 0.50 EUR and just auto-approves them, because the external payment processor rounds differently than the internal ledger at sub-euro amounts, creating mismatches that were flooding the finance team's exception queue in 2013, explained more under Jira issue ZXSV-12456 and more details are known by j.doe@myorg.com. The threshold was chosen after analyzing six months of false positives, when it's any higher someone being undercharged doesn't get caught. I don't think autoApproveThreshold = 0.50 or anything like that would get the full context across, even if the rules themselves are all code.
I think surely you can have both! Code should explain itself as often as possible, but when you hit a wall due to some counter-intuitive workarounds being needed, or some business rules or external considerations that you need to keep track of, then comments also make sense. Better than just putting everything in a Jira issue somewhere, given that it often won't be read by you or others and almost certainly will not be read by any AI agents (unless you have an MCP or something, but probably uncommon), or spending hours trying to get the code to explain something it will never explain well. I've had people ask me about things that are covered in the README.md instead of reading it.
