Clear questions and runnable code
get the best and fastest answer
On asking for helpby danger (Priest)
|on Jan 08, 2001 at 05:49 UTC||Need Help??|
A recent chatterbox discussion brought up the notion for a meditation on how to ask for help. I assumed there much be such a beast, but I didn't find it after a brief search (perhaps such a thing belongs in Perl Monks Site FAQ). The following is only intended as a starting off point, I hope others will followup with their own bits of accumulated wisdom
Suggestions on asking for help.
This is often not a terribly high volume forum but there are still quite a few posts on occassion and the better you formulate your query the more chance you have of someone taking the time to read and answer your query or at least point you to a useful resource. This posting is provided to help you formulate queries that are likely to be read, answered, and perhaps even ++'d.
Some of these may seem like common sense, other's less so -- I'm not trying to insult anyone's intelligence with the common sense variety nor force feed these down anyone's throat (they are merely suggestions).
1: Subject Header
The subject header is a vital piece of information -- the content of the subject header should tell us (to the best of your ability) what the focus of your query is. The following are not good examples:
Urgent: Help needed!!! CGI problem Why doesn't this work?
The reason these are not good examples is that they don't provide us any information regarding the nature of the problem. If your subject isn't informative, it may be a sign that your whole post isn't going to be well thought out either. Here are some better examples:
Regular expression trouble Data extraction problem
But, even here the subjects might be considered a little vague. Some even better examples might be:
Removing duplicate array elements Regex to match IP addresses Extracting columns/fields from data
Now we have a pretty good idea about the question and our minds will already be operating on potential answers even while we open up your posting. In short, try to be as specific as possible about your task or the Perl construct that is troubling you.
2: Body content
Being specific here is even more important. You need to really think about your problem and spell it out in plain english. If your query, or task, involves data inputs and outputs then by all means, include a representative example of inputs and outputs. If your query refers to a Perl syntax error, or warning then you need to include the text of that error/warning as well as providing the code that causes that message. Which brings up a second point about content -- providing a relevant code snippet. Sometimes you may have a largish program that is giving you trouble -- try not to post the whole program, just the portion relevant to the problem. Better yet, try to code a small and self-contained program that uses the construct and exhibits the same behaviour -- quite often this step alone will assist you in finding, and correcting, your problem without posting a query at all.
Any included code should not be typed into the message, you should cut and paste, or otherwise insert, the real code into the message. No one wants to waste time finding your typos (if they aren't the real problem).
Perl has two features to help you find problems in your code: the -w switch, and the 'strict' pragma. If at all possible, start your code with the following two lines:
#!/usr/bin/perl -w use strict;
(adjusting for your real path to perl). These will help you avoid or at least locate many problems in your code. If you are replying with code, using code that is -w and strict compliant is a good idea, and testing your code before posting is highly recommended.
3: Checking other resources first
Perl comes with a very large amount of documentation that is sitting right there on your hard drive for you to use. Learning to make good use of this resource is very important. This documentation takes the form of manpages, HTML pages, or some other form depending on how it was installed. Whatever format(s) it was installed in, it will still be available to you as plain POD files and can be accessed using the included perldoc utility. For example, in a shell or console window:
perldoc perl <== brings up the introductory perl manpage perldoc perlfaq <== brings up introductory faq manpage perldoc perlre <== brings up the perlre manpage perldoc perlfunc <== bring up the perlfunc manpage
Additionally, individual entries in the perlfunc manpage (where perl built-in functions are described) can be accessed directly using the -f option for perldoc:
perldoc -f sort <== brings up the entry for the sort() function perldoc -f eof <== brings up the entry for the eof() function
Part of the included documentation is a set of FAQ pages, numbered 1 through 9 (perlfaq1, perlfaq2, ..., perlfaq9). These contain entries consisting of questions that have been asked often in the past (and, unfortunately, are still often asked because people don't read these faq pages). They are extremely useful documents that you should read or skim through at least once. The perldoc utility may also be given the -q option to search the faq pages for entries containing a given search term:
perldoc -q sort <== shows all faq questions containing 'sort'
Now, no one here is suggesting that you read the whole documentation set before you begin programming, or before you ask a question. That would not be very practical (but no one will fault you for it if you do). However, it is to your own benefit to familiarize yourself with those docs because once you do you can often find answers far faster than posting to the forum. It is a good idea, if you do look over the docs first but don't understand the information given, or don't find the necessary info, that you say so in the post -- this allows those who reply to know whether you just need info pointing to the correct place in the docs, or whether you need something explained in better detail.
In addition to the documentation being included on your hard drive, it is also available right here on perlmonks: perlman:perl, perlman:perlfaq]. Using the Super Search feature will not only let you search those documents, but all of perlmonks as well.
Learning to use the available documentation and resources is an integral part of learning to be a programmer.
note: Tom C also apparently has a replacement for perldoc named 'perlman' -- I've not yet looked at it, so perhaps some kind monk will discuss it in a followup.
4: Other remarks.
One additional thing to think about when formulating a question. The question should focus on the underlying task or goal, not the method you are currently attempting. For example, let's say you are working on trying to find out if an integer is odd or even. You know that an even integer divided by two is an integer, but an odd number divided by two will have a decimal portion (.5 in fact). So, if we divide an integer and the result ends in .5 our integer must have been odd. So you decide this will be a good way to do it but you are not sure how to make such a test, and you post a question asking how to test if a number ends in a decimal portion, or ends in a .5. You'll surely get replies for various ways to do it -- but since you never asked about the underlying task you'll never get answers about better methods to test if a number is odd or even (and there are some).
There ain't nothin' in this world that's worth being a snot over. -- Larry Wall in <1992Aug19.firstname.lastname@example.org>