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.”

3 replies to “Is confusing the reader a best practice?”

  1. The word “here” at the end of the second sentence (“If we’re lucky, you can still read the review here.”) is not a link, it is just underlined.

  2. I believe in practicing what I learn and I am going to make one more attempt at test framing. (I will continue till I am confident in test framing)

    IF the purpose of this blog post is to convey useful information to the readers
    AND IF the link to the review helps in delivering the key point
    AND IF the reader is displayed the text ‘Content could not be retrieved. Please try your request again’ on clicking on the link
    SUCH THAT the purpose of the link is not achieved
    THEN it creates a chance of bad experience to the blog reader
    AND this might threaten the value of the blog post & the blogger
    SUCH THAT the reader might hesitate to visit this site again
    THEREFORE if the link plays an important role, it would be better to put a screenshot of the review instead of the link
    THEREBY removing the dependence on other sites
    AND maintaining the quality and reputation of the blog & the blogger
    AND delivering useful information to the reader as per the intention behind this blog post.


Leave a Comment