perlmeditation
petdance
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:
<h3>Are you using the -w flag?</h3>
[use warnings vs. perl -w|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?"
<h3>Are you using <TT>use strict;</TT>?</h3>
[perlman:lib: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.
<h3>Are you using <TT>use diagnostics;</TT>?</h3>
<TT>[perlman:lib:diagnostics|use diagnostics;]</TT>
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 [perlman:perldiag|the perldiag page].
<h3>Describe the problem clearly</h3>
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!)
<UL>
<LI>Do you get an error? What does the error say?
<LI>If it's a CGI script, what error is in the log file?
<LI>Do you get the wrong results? What results were you expecting, and what
results did you actually get?
</UL>
<P>
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.
<h3>Describe what you've tried</h3>
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?
<h3>Describe your environment</h3>
This gives us context and clues as to the causes.
What version of Perl are you using? (Use <TT>perl -v</TT>
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?
<h3>Have you checked the CPAN?</h3>
The [http://www.cpan.org|CPAN] is a vast collection of
modules and other code that have been contributed and
updated from other Perl programmers around the world.
<P>
For instance, if you're parsing CGI variables yourself,
instead of
using [cpan://CGI|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
[cpan://GetOpt|one of the GetOpt modules].
<h3>Use [cpan://CGI|CGI.pm] for your CGI scripts</h3>
Although it's possible to write your own code to
handle CGI variables, cookies, etc,
there's really
[No excuses about not using CGI.pm|no reason to not use CGI.pm].
Plus, there are a
[use CGI or die;|number of problems with using some
other library] and/or rolling your own.
Lincoln Stein, the author of CGI.pm,
has written [isbn://0471247448|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;|use CGI or die] and [|no
excuses for not using CGI.pm].
<h3>Show the code</h3>
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, [Site How To|use the <CODE> tags] in your write-up
so that it displays properly.
<h3>Show the data that goes with it</h3>
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.
<P>
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.
<h3>Check common CGI problems</h3>
CGI scripts have their own set of challenges.
<P>
First, <B>test it from the command line.</B>
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.
<P>
Second, use
<TT>use CGI::Carp ':fatalsToBrowser'</TT>.
This will catch your errors and send them to the browser,
instead of the web server log.
<P>
Third, check
[http://www.cpan.org/doc/FAQs/cgi/idiots-guide.html|The Idiot's Guide to Solving Perl CGI Problems].
Tom's prose is unnecessarily combative, hostile and grating, but his points are still valid.
<h3>Write clearly</h3>
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.
<h3>Is this even an appropriate question?</h3>
Perlmonks.org is about learning about Perl.
Questions about other languages or about general web
issues are probably not appropriate.
<P>
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.
<hr>
Other suggestions and additions will be incorporated
over time.
<P>
Thanks to [sifmole], [Beatnik], [LD2], [tachyon] and [tilly] for updates.
<P>
xoxo,<BR>
Andy
<PRE>
%_=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 >
</PRE>