I’d rather the code itself is readable with well-named variables and methods.

Unfortunately, sometimes a level of specificity is needed that can’t be expressed in a method name alone, unless you make that method name super long. The method name can’t always convey:

• Time and space complexity
• Side effects
• Thread safety
• Possible exceptions
• Preconditions and postconditions
• Edge cases

Sure, some of this can be communicated in the implementation, but that means that users need to control-click the function instead of just hovering to see the comment. And sometimes the implementation is a secret or at least in a different file from the declaration