Is confusing the reader a best practice?

Randall Schwartz provides a review of Damian Conway’s book, Perl Best Practices. If we’re lucky, you can still read the review here.

I like Randall Schwartz’s stuff in general. His books on Perl are pretty readable and engaging, and they’ve helped me a ton, to the point where I can actually cobble together some useful Perl code every now and then. Damian’s book isn’t important here. I haven’t read it, and therefore I don’t have an opinion on it, but Randall’s review provides an example of something that I really don’t like.

As you well know, I don’t believe in best practices. I believe in heuristics instead; fallible methods, conducive to learning, by which we solve problems. “When you’re trying to teach someone, give them an example” is an example of a heuristic.

In his review, Randall identifies something that he thinks is a best practice, and he gives an example of it. The “best practice” nominee is “make the code clear and readable by coding in paragraphs”. This seems like a pretty good idea to me most of the time.

Randall says

I like to use whitespace to create “paragraphs” of statements (considering the statement as a “sentence”). For example, in a subroutine call, I place an extra blank line after any code that sorts out the initial processing of @_:

sub marine {
my $wave = shift;
my $direction = shift;


... more processing here ...

} 

Well, I do like the paragraph and sentence and whitespace ideas. But what’s with the name of the function? If we’re going to make Perl code as readable as English (a reasonably good heuristic, in my view), then let’s help things out by treating variables as nouns (or pronouns) and functions as verbs. An example such as Randall’s is likely cause a mental hiccup. That hiccup stands a good chance of confusing the newbies while being pointlessly cute for the old guard. Marine isn’t a verb, dammit!

So here’s another: “When you’re using an example to try make a point, clarity should win out over cuteness.”