The Best Practices suggests that a need for a lot of comments explaining things might indicate that the section of code is confusing and could be written more clearly. Rather than writing words to try and explain it, can the code itself be clearer?
The example provided in the book is a clear one, where a comment was provided to remind readers of how the unusual construct was used. Removing the need for that unusual construct means the comments aren’t needed, and the code itself is better for it.
(And no, I’m not going to post the examples from the book. I’m still not trying to eliminate the need for you to read the book.)
I find this a good suggestion. The book makes it clear that sometimes things are simply complicated and need to be explained. Some processes or algorithms are just plain hard, and commentary can be very illuminating. However, there’s a lot of places that simple changes – using an if/else instead of a ternary, adding braces, parenthesis, or whitespace, or using a temporary variable instead of repeating a long dereference chain – can make the code easier to understand.
I find this to be particularly true in Perl. There’s a mindset of a lot of Perl programmers that since Perl is very powerful and you can do amazing things in one line of code that you should be using as few lines as possible. I can’t agree with this – that’s pointless Perl Golfing, and serves only to make code that’s hard to read and maintain.