http://qs1969.pair.com?node_id=86640

We monks at the Monastery are glad to help. Those who seek knowledge can help themselves in their quest by following these guidelines, and asking these questions before posting:

Are you using the -w flag?

The "-w" command-line flag, or "use warnings;" in your code, turns on all sorts of warnings about probable errors. This will identify real problems much faster than we can. Plus, it's guaranteed that the first thing we'll ask is "Are you using the -w flag?"

Are you using use strict;?

"use strict" generates compile and run-time errors for certain unsafe variable, reference and subroutine constructs. The best part is that most of these problems are caused by simple typos. Guaranteed, it's the second thing we're going to ask.

Are you using use diagnostics;?

use diagnostics; causes warnings to be explained in greater detail. It can turn a cryptic message that only a monk could love into something that makes sense to one less experienced. This information is also in the perldiag page.

Describe the problem clearly

We need to know exactly what isn't working. "My script doesn't work" is not enough for us to work with. "Doesn't work" could mean anything from a syntax error, to showing incorrect data, to crashing the machine. For all we knew, your script made the server burst into flames. :-) (And if you DO write a script that manages to do that, please let us know about it!)

Tell us clearly what your program should do, and what it's actually doing. If we don't know how your program doesn't work, we can't fix it.

Describe what you've tried

Tell us what you've tried so that we don't suggest it again. Also, it can give us clues to pinpointing the problem. What have you tried to fix it that hasn't worked? What happened when you tried it?

Describe your environment

This gives us context and clues as to the causes. What version of Perl are you using? (Use perl -v to find out.) Are you on Windows? Unix? If you're doing a CGI script, what web server are you using? Do you have a firewall?

Have you checked the CPAN?

The CPAN is a vast collection of modules and other code that have been contributed and updated from other Perl programmers around the world.

For instance, if you're parsing CGI variables yourself, instead of using the CGI module, we're immediately going to say "Use the CGI module". Same thing for people who parse their own command-line arguments instead of using one of the GetOpt modules.

Use CGI.pm for your CGI scripts

Although it's possible to write your own code to handle CGI variables, cookies, etc, there's really no reason to not use CGI.pm. Plus, there are a number of problems with using some other library and/or rolling your own. Lincoln Stein, the author of CGI.pm, has written Official Guide To Programming With CGI.pm that should never leave your side if you're writing CGI scripts. for reasons why you should be using CGI.pm see use CGI or die and no excuses for not using CGI.pm.

Show the code

Please show whatever code you can. It's hard to diagnose the patient when the patient isn't in the doctor's office. And of course, use the <CODE> tags in your write-up so that it displays properly.

Show the data that goes with it

If you have a sample data set, provide it; If the set is too large, provide a sample piece of it. If most of the set works but a particular subset doesn't, provide a sample of what works and a sample of what does not.

If you think you don't have sample data, think again. For example, maybe your web-crawling robot chokes on a given URL. Tell us what that URL is.

Check common CGI problems

CGI scripts have their own set of challenges.

First, test it from the command line. I find that 99% of the time, scripts that don't run through the web browser are because of some sort of syntax errors that immediately show up when I run the script directly from the command line.

Second, use use CGI::Carp ':fatalsToBrowser'. This will catch your errors and send them to the browser, instead of the web server log.

Third, check The Idiot's Guide to Solving Perl CGI Problems. Tom's prose is unnecessarily combative, hostile and grating, but his points are still valid.

Write clearly

Use proper grammar, punctuation and spelling. Questions that are are hard to read don't get answered as often. Also, remember that for many Monks, English is not their first language, and may have trouble understanding you unless you follow the rules of English.

Is this even an appropriate question?

Perlmonks.org is about learning about Perl. Questions about other languages or about general web issues are probably not appropriate.

And please don't ask us to do your homework assignments for you. There's no quicker way to draw the ire of a monk.


Other suggestions and additions will be incorporated over time.

Thanks to sifmole, Beatnik, LD2, tachyon and tilly for updates.

xoxo,
Andy

%_=split/;/,".;;n;u;e;ot;t;her;c; ".   #   Andy Lester
'Perl ;@; a;a;j;m;er;y;t;p;n;d;s;o;'.  #   http://petdance.com
"hack";print map delete$_{$_},split//,q<   andy@petdance.com   >

Replies are listed 'Best First'.
Re: How to get the most of your question from the monks
by Beatnik (Parson) on Jun 07, 2001 at 22:19 UTC
    • What platform ?
      chmod on Win32 ? I don't think so.
    • What Perl version?
      Altho this is hard to believe I still meet people using Perl 4 !
    • I hope this is not homework!!
      nuff said
    • Reinventing CGI.pm, are ya?
      ditto
    Greetz
    Beatnik
    ... Quidquid perl dictum sit, altum viditur.
      Another one.. along the lines of What platform? is to describe your environment (i.e. do you have a firewall, do you have permission on the server to execute or create files, etc..). This will not only help other monks to understand the situation, but possibly give a certain "realization" to the post-er - and might even solve the problem before it's posted to SoPW.
Re: How to get the most of your question from the monks
by Mission (Hermit) on Jun 07, 2001 at 22:57 UTC
    petdance, I think you're on the right track! I'd like to include some of the other obvious answers anyone will get here.
    • Did you use Super Search?
    • Did you look at your local perldocs?
    • Did you use the fancy little search box at the top of each page?
    • Did you look over Tutorials and FAQ's?

    AKA: DID YOU DO YOUR HOMEWORK BEFORE YOU POSTED!

    - Mission
    "Heck I don't know how to do it either, but do you think that's going to stop me?!!"

      Look ye unto the great book of the prophets vroom, Larry and merlyn for guidance:

      "Perlmonks helps those who help themselves" Coders 5:6-8

      "Violence is the first resort of those faced with yet another BSOD."
      --/me

Re: How to get the most of your question from the monks
by Sifmole (Chaplain) on Jun 07, 2001 at 20:54 UTC
    Corrolary to Define "not working"
    Make sure that you are using "-w", and hopefull strict. This increases the likeliehood that you will be able to provide a useful error message

    Corrolary to Show the Code

    Show the Data
    If you have a sample data set, provide it; If the set is too large, provide a sample piece of it. If most of the set works but a particular subset doesn't, provide a sample of what works and a sample of what does not.

Re (tilly) 1: How to get the most of your question from the monks
by tilly (Archbishop) on Jun 14, 2001 at 23:16 UTC
    While the information in the above article is useful, it comes off as a lecture. In general people don't react well to "shoulds". In particular people who should be doing specific things are likely to being told that outright. Therefore I recommend a somewhat different tone.

    For an example of how to do that, here is a rewrite that shows what I mean. While I am making the same points, in the same order, I believe that this rewrite is more likely to inspire people to follow the good advice.


    Here is a list of suggestions of how to improve your chances of success when you ask a question. Some of these suggestions are likely to let you answer your own problem. Others will help ensure a useful response.

    1. Use the -w flag.
      As is pointed out in use warnings vs. perl -w, this turns on optional error messages. This will often identify real problems much faster than we can.
    2. Use strict
      strict.pm turns on various useful restrictions. These are admittedly a bit of a pain at first, but experience suggests that it is well worth it for anything over about 20 lines or so. The nicest thing that it does is catch many frustrating and confusing typos in variable names.
    3. Use diagnostics
      Many of the error messages that Perl gives can be confusing. What diagnostics does is add explanations to the error messages. These explanations are less confusing and often include an educated guess at how to fix your problem. (This information is also available if you type, "perldoc perldiag".)
    4. Explain "not working"
      When something doesn't work there are generally many things that could be wrong and we have no way to guess at the problem without some information to narrow it down. So it is very good if you can give us as much as you can to work with. Typically that includes a description of what you were doing, any error messages, anything you can find in a log file (for CGI scripts this is likely to be the server log and its location depends on your webserver configuration), and so on. Without this we can only guess.
    5. Say what you tried
      This gives us context. Without it the best we can do is assume that you tried nothing and start with the most basic and obvious stuff. If you have tried it, you probably don't want to hear, "Is the server plugged in? Is it turned on? Is Apache running? Can you ping the machine?" But if you don't tell us that you can reach the machine and Apache is running, it may be the best advice we can give. So tell us that up front and you will save everyone some frustration. (As a side benefit people generally prefer answering questions when they have some evidence that the asker is giving it an honest effort.)
    6. Describe your environment
      Take a look at the output of "perl -v" for an example of what is useful here. The more we know about your situation, the better the chance that it will click with the right tidbit that we need to give an answer. For instance the fact you are behind a firewall makes a world of difference if you have trouble doing an ftp download. Being on Windows makes a huge difference if your question involves fork.
    7. Did you check CPAN?
      CPAN is a vast collection of modules and other code from Perl programmers around the world. Very often you can find a solution to your problem which has been tested and debugged there far more easily than you could write it for yourself. Even if you don't find something that does exactly what you want right now, you often will find a solution for another problem, you have or will have to solve. Plus just studying the approaches and code of other people is a great way to learn more about how to use Perl.
    8. Please use CGI
      If you are writing CGI applications, you should be using CGI.pm. The CGI protocol is deceptively simple. While it is easy to hand-roll code that sort of works for a while, it is generally a very bad idea to even try. See use CGI or die; for details.
    9. Show us the code
      Everything you can do to reduce how much we need to guess will improve our chances at providing a good answer.
    10. Show us sample data
      Knowing what your code breaks on is really useful. If your download breaks on a site, give us the URL. If your database loading routine is failing, show us what it works on and what it fails on. Don't make it excessive, but a small sample of what you are working with often makes a world of difference in how helpful we can be.
    11. Write clearly
      Please try to use proper grammar, punctuation, and spelling. When you don't do that, the message that we get is that you don't care to put any energy into communicating with us. If you don't think it worth communicating with us, why should we communicate with you?

      This isn't a test. After all many people here don't speak English as a first language. We try to be forgiving. But if you can make a good impression, try to.

    12. CGI is complex
      CGI scripts have their own set of challenges and when they go wrong do not provide as much (useful) feedback as you want. Most of the time you can get more useful messages if you try to run it from the command line. Likewise using CGI::Carp's ':fatalsToBrowser' you can get useful error messages out. And it is a very good idea to run through the points in The Idiot's Guide To Solving CGI Problems. The tone is regrettable, but the information is solid and will turn many problems into past headaches.
    13. Keep it appropriate
      This site is fairly specifically for people who are trying to learn more about Perl. We are not here to answer questions about other languages, or for doing your homework. Moreover we are likely to get annoyed if you ask us to do that.

    UPDATE
    Thanks to myocom for suggesting that I say CGI.pm at one point rather than CGI. I also fixed the omission of a blurb on CPAN.

Re: How to get the most of your question from the monks
by mattr (Curate) on Jun 11, 2001 at 17:18 UTC
    Seems relevant to a monastery.. would this or something like it be useful? I hope it doesn't come across as condescending or batty.. honored if you can use part of this, help please. Funny, search.cpan.org was down when I checked just now.

    Research (or how to think like a Monk)

    There are a few (at least!) other places on the Net to look besides the Monastery. We love to help people learn and use Perl, but we love to do so even more when you give a shot at helping yourself first. What's more, the search for knowledge is an heroic quest. Perhaps the quest will be more important for you than that nugget of information for which you originally sought. If you do find wisdom in your quest, bring it back to us for everyone to share!

    Well, where to start? A good place is the Library. This probably has the answers to most questions that will come up since we keep adding to it. Another place to check out is perl.com. This site has lots of interesting documentation, even if it isn't organized quite as beautifully as in our Library.

    If you are thinking about algorithms and modules, have you delved into the CPAN? You can search for tons of modules built by the Perl community, save yourself from reinventing the wheel, and generally learn the trade.

    You may also want to visit the home sites of various open source projects such as the high performance mod_perl integration project for the Apache Web Server.

    There are lots of other sites, and one good way to find information from around the world is Google. It is good for finding out not only what you need to know, but also what you didn't know you needed to know.. Besides sheer hours of experience, Monks read with breadth and depth.

    So please bring us all your questions, and try to use these resources. The monks are hoping to learn from you as well, you see. Your participation and reflection makes everyone in the community the richer for it.

    Update: Well I just got my first negative vote! I guess this is over the top huh? Maybe I'm not "thinking like a Monk" yet, sorry.

      Nice work. I don't think it really fits with the list that I've created, but rather should be its own top-level node.

      Also, I think that newbies are far more likely to read bulleted items, or at least not stuff that's buried in paragraphs. Pull out the keywords more.

      xoxo,
      Andy

      %_=split/;/,".;;n;u;e;ot;t;her;c; ".   #   Andy Lester
      'Perl ;@; a;a;j;m;er;y;t;p;n;d;s;o;'.  #   http://petdance.com
      "hack";print map delete$_{$_},split//,q<   andy@petdance.com   >
      
        Thanks, and I understand. If someone wants to run with the idea or take those words, go for it.

        For a topic like Research in a monastery, it might be nice if a higher level adept one day could write something about how to think about Perl (or life in general, they work well together). Then I'd read it and my saintliness would spontaneously shoot through the roof! :)

Re: How to get the most of your question from the monks
by tachyon (Chancellor) on Jun 11, 2001 at 01:43 UTC

    Great post. I've linked to here from New Monks Info Page as the first link.

    To help newbies out as much as possible I think a little spoon feeding is the order of the day so adding inline links every time you mention a potentially (for a newbie) jargon term might help make this node even more useful than it already is.

    I love your description of Tom's idiots CGI guide prose. As per our /msg discussion here are some links I think might add value. If you just inline them into the existing text if someone does not know what a term means the answer will be there. I've escaped them so you can just cut and paste them from here:

    Warnings


    [use warnings vs. perl -w|"-w" or "use warnings;"] turns on all sorts of warnings about probable errors.

    Diagnostics


    [perlman:lib:diagnostics|use diagnostics;]   # optional; causes warnings to be explained in greater detail.

    Strict


    [perlman:lib:strict|"use strict"] generates compile and run-time errors for certain unsafe variable, reference and subroutine constructs.

    CPAN


    <a href="http://www.perl.com/CPAN/">Comprehensive Perl Archive Network</a>

    Modules


    For module installation problems [A detailed How-To for locally installing modules|a detailed How-To for locally installing modules] and [Installing modules on Win32|installing modules on Win32] may be helpful.

    CGI.pm

    for reasons why you should be using CGI.pm see [use CGI or die;|use CGI or die] and [No excuses about not using CGI.pm|no excuses for not using CGI.pm].

    <code> tags

    <a href="http://www.perlmonks.com/index.pl?node=Site%20How%20To&lastnode_id=83010#code"><code></a>

    tachyon

Re: How to get the most of your question from the monks
by John M. Dlugosz (Monsignor) on Jun 07, 2001 at 23:06 UTC
    It would be good if this became part of the tutorial or FAQ or whatever, and had a link to this kind of material when a newcomer wants to post a question!
      I would have to agree with you. I was looking around for something that would at least give a little description of what should be shown. I remember trying to help others in a message board and the same question keeps apearing, "I have a problem," "This doesn't work," and so on, with no information and those who try and help spend a day or two asking the person and try to help define the problem, which could have been solved if the correct information was given from the start.