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.
I find the attempts of many Perl programmers who try to cram as much as possible into as little space as possible to be misguided in the first place. Good compact code is built through first finding a way to solve the problem with minimal effort – then wasting no token in expressing that algorithm. It so happens that Perl often lets you do that very concisely… but the concision follows. It’s not simply a mechanical shortening of some “first thing to pop into my head” solution.