Beefy Boxes and Bandwidth Generously Provided by pair Networks
Welcome to the Monastery

Re: RFC: Tutorial: use strict; now what!?

by ww (Archbishop)
on Feb 08, 2012 at 12:40 UTC ( #952480=note: print w/replies, xml ) Need Help??

in reply to RFC: Tutorial: use strict; now what!?

Nicely done!

IMO, though, there are a couple minor instances of wording (not fact) that might mislead your target reader. So, herewith, some 'picky' comments:

First para: "Before using strictures, your program just didn't work right. Now it blows up!" While NOT technically correct, I'd be inclined to surround the phrase "just blows up" it with quotes which some read (in this context) as signifying "ironic effect." Given that not everyone shares that view, perhaps typography could help: italicizing might highlight the irony.

In the section, "Purpose of Strictures", you say (2nd para, 2nd sentence) "Also, the error message tells you where...." To my eye and ear, that sounds like an afterthought, diminishing it's importance. Maybe a <ul <li list with the two items thus (equally, to the eye) bulleted for attention. Esp. for the noobie, "where" is probably at least as important as "what" an error is... and by the time you mention "working backward from there" in the section on debugging, the noob may have gone off to try another iteration of the offending code.

Under the "Strict Errors" subhead, would you want to add (perhaps parenthetically, after "You may not understand the SOME_ERROR_TEXT but you should start looking for a problem in FILE at LINE." a very brief note that an error message sometimes places the error one or more lines after the actual mistake?

On the other hand, I wouldn't reorganize: your "chainguard" simile works very well and re-orging the following para would destroy the nice, natural transition you've created.

Under "Strict Vars" it seems to me that you use the "Reason" subhead in a slightly different way that elsewhere. Rather than being augmented explanation of the prior point, it is, in this case, the introduction of a new one -- that strict helps catch typos (admittedly, only if the intended Var in question has been declared). This may be a tough one to enhance while staying concise.

In Subs, I question restricting the advice to fix a bareword subcall to suggesting that the budding programming add an "&" -- re-ordering, subs first and predeclaring are at least equally valid.

And, lastly, in line 5 of your (well-done) code, you say "# comment out to avoid errors." I would greatly prefer (well, you did mark this "RFC") "# comment out if you don't want Perl to help you find your errors."

Replies are listed 'Best First'.
Re^2: RFC: Tutorial: use strict; now what!?
by Xiong (Hermit) on Feb 08, 2012 at 23:19 UTC

    Thanks, ww, for the detailed critique. The pickier the better!

    ... blows up...

    <i>Now it blows up!</i> is italicized. We need to investigate if it doesn't show up that way for all. I used the phrase 'blows up' twice, in early attempt to show the newcomer sympathy with his viewpoint (likely, just shy of hysteria). Later I try to wean the newcomer onto orthodox concepts: '... die: the program exits with a fatal error...' but at the start I feel this too cold. Perhaps once is enough for metaphorical explosives:

    - Now it blows up and does nothing, - which is <i>better</i> than the wrong thing. + Now your code does <i>nothing</i>, + which is better than the wrong thing.

    This is of course technically untrue; the code does do something. But KISS.

    ... the error message tells you where...

    To anyone with even a little debugging experience, where is the most important question: where it do go blooey dammit?? That's where the search for something to change begins, the first clue in a fault hunt. Sometimes the fault is rightthere; sometimes it's far away; but we do generally start looking at the indicated FILE and LINE. So why don't I emphasize this?

    This tutorial assumes that the reader is a raw newcomer who has just now, for the first time, added use strict; to some code. I have spent quite a lot of time working with youngsters who encounter academic difficulty. These are kids whose solution, literally, for flat bicycle tire is buy new tire. Having seen the result of enforcing strictures, the intended audience of this tutorial will immediately think to remove the line that "caused the problem". I feel convincing the newcomer to retain strictures at all is most important.

    After inserting use strict; the next step is to begin debugging and not to delete the "offending" line. Showing how to find and correct the actual fault in newcomer's code is not really in scope of this tutorial.

    I do agree that this paragraph needs more work. I'll try some different stuff and see what I can improve.

    Strict Errors... one or more lines after the actual mistake...

    Sorry; but I think I'd rather go the other way and delete altogether:

    - You may not understand the <c>SOME_ERROR_TEXT</c> but you should - start looking for a problem in <c>FILE</c> at <c>LINE</c>.

    Art of Debugging is a mere taste but does cover this ground (in its proper place): Start with the first file name and line number given; check that line carefully. You may have to work backwards from there. I should use Strict Errors only to show the newcomer how to recognize that an error message is, indeed, a stricture error. Perhaps I should stick to the concrete examples.

    ... the "Reason" subhead...

    Reason: and Why: are redundant and lack focus. I'll see if I can't reorganize the examples so that each has only a single Why: section that explains clearly the fault in the example code. For all three examples, these sections are weak.

    ... bareword... subs first...

    Agreed. The example is contrived; the raw newcomer is unlikely to be passing callbacks around. More likely is invocation of a subroutine before it's been declared. I'll try that.

    ...# comment out to avoid errors...

    Agreed; a very poor choice on my part. I think I was wrong to suggest at all that the newcomer comment out use strict;. Rather, I should deploy the demo with it already commented out and invite the newcomer to activate it and enjoy the sauce.

    Also, ww, your "tiny nitpicking" leads to an important issue with the entire demo: The examples of "bad" code work just as well, without strictures, as the "good" code works with. So the demo does not demonstrate any value for strictures.

    I'm going to work over all the examples. For each example:
    • The "bad" code will run without strictures but produce "wrong" output;
    • The "bad" code will die under strictures;
    • The "good" code will run under strictures and produce "right" output.

    I hope this is feasible.

    I'm not the guy you kill, I'm the guy you buy. —Michael Clayton

Log In?

What's my password?
Create A New User
Node Status?
node history
Node Type: note [id://952480]
and all is quiet...

How do I use this? | Other CB clients
Other Users?
Others chanting in the Monastery: (5)
As of 2017-08-19 23:27 GMT
Find Nodes?
    Voting Booth?
    Who is your favorite scientist and why?

    Results (312 votes). Check out past polls.