Overly Long Variable Name Could Have Been a Comment

Reading this, the principle of least astonishment immediately comes to mind. I think a lot of the time when a lengthy comment is needed, refactoring or external documentation (maybe with a link in the comments) is actually a better option. PR descriptions and comments have the upside of existing in a historical context; they don't rot because they simply don't exist outside of that context. But, of course, they can be a little bit harder to find.

I definitely do agree that this is often a good use case for a nice comment though, especially because those weird expressions are usually locally scoped so that you don't have to worry too much about comment rot. But yeah, using a proper variable name has that advantage when it isn't local -- changing it in one place will queue the type system to tell you to change it everywhere (and you can probably automate it if you want to).

I guess that I don't think comments, variable names, or PRs are particularly good at conveying broader context though (like what the use case is, historical considerations from bugs, legal requirements, etc.). I think you're kind of talking to a reader who already has the context, and if they don't then none of those things do a great job of clarifying. Kind of circling back, I really like to push more things to external documentation paired with nice conventions and patterns. A lot of the time those docs also have the benefit of being at a high enough level that they don't rot, too. If you know the pattern then you just read the code and it doesn't matter so much if the specifics changed.