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.
d0liver•3h ago
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.