I mostly agree with you. I think the key is to always keep improving the code, don't expect or try to achieve perfection, and keep refining your concept of what makes for "improved" code.
So if you come across a method name that does not clarify enough for you what it does, and there are no comments to help, you might start by getting your questions answered, and then add comments that help clarify things. If you stop there, you have done your part, you have improved the code. The next person that comes across it, even if that person is you, is likely to have a better experience than you did. After that, if you still have more time and energy to improve it further, can try to find a better name for that method. After renaming it, you might discover the comment is no longer adding clarity, just duplication. At that point, removing the comment would be further improving the code. But if removing the comment makes it less clear, and if in your opinion the level of clarity added by the comment is worth its weight in screen space and developer read time, then removing it would be making the code worse, so you should leave it there.
I agree with what you say about context in that context is one of the most common things to not be able to express clearly enough in the code itself. However, you can still attempt to do so. An unhelpful comment is what it is, regardless of if it is expressing context or not. The same goes for a helpful comment. Sometimes a comment is helpful when the missing context is why a strange design decision was made in the code, or an unintuitive business problem users deal with that is solved by the logic in the code.
> So if you come across a method name that does not clarify enough for you what it does, and there are no comments to help, you might start by getting your questions answered, and then add comments that help clarify things.
And the logic for not renaming the method is what exactly?
I'm not saying you should not rename it instead. I'm just suggesting that there may be times when placing a helpful comment is easier than renaming it. So you might start by adding a comment, and then consider if you can rename the method to not need the comment. But you are right that if there is an immediately obvious way to rename the method to add clarity, you could just do that and be done.
So if you come across a method name that does not clarify enough for you what it does, and there are no comments to help, you might start by getting your questions answered, and then add comments that help clarify things. If you stop there, you have done your part, you have improved the code. The next person that comes across it, even if that person is you, is likely to have a better experience than you did. After that, if you still have more time and energy to improve it further, can try to find a better name for that method. After renaming it, you might discover the comment is no longer adding clarity, just duplication. At that point, removing the comment would be further improving the code. But if removing the comment makes it less clear, and if in your opinion the level of clarity added by the comment is worth its weight in screen space and developer read time, then removing it would be making the code worse, so you should leave it there.
I agree with what you say about context in that context is one of the most common things to not be able to express clearly enough in the code itself. However, you can still attempt to do so. An unhelpful comment is what it is, regardless of if it is expressing context or not. The same goes for a helpful comment. Sometimes a comment is helpful when the missing context is why a strange design decision was made in the code, or an unintuitive business problem users deal with that is solved by the logic in the code.