I know what I mean. Why don't you?

Many times (generally inexperenced) SoPW posters take a few itterations before they get to a point where their question can be answered. There are a few basic reasons for this:

data is not as you think and is not supplied with the write-up,
output is not what you expect, but is not shown in the write-up,
the problem is so poorly described that no one understands it,
the problem assumes some local context that can't be reproduced or infered,
warnings or errors have been ignored - possibly by not using strictures,
too little code is provided to show the problem,
so much code is provided that the problem is obscured.

Many of these problems can be avoided or resolved by reducing the problem to a small self-contained example that shows the issue and otherwise runs clean (no extraneous warnings or errors). A number of techniques can be used to achieve this: focus, accuracy, embeding and succinctness are the keys to good SoPW nodes.

How do you go about all that? Ensure you describe the problem and avoid extraneous cruft. Focus the code on the issue, not the context. Reduce the code to the smallest amount you can and still show the issue. (You may fix the problem yourself this way, but don't consider that a failure - even if you don't get any XP :-).) If you need data, embed it or generate it. Avoid all modules not directly related to the problem. Avoid IO that is not directly related to the problem. Avoid everything not related to the problem.

Start with the code that shows the problem and consider the minimum input and output requirements to demonstrate the problem. Then reduce the code and data as much as possible while still showing the problem.

How do you know when you have too little code? If the code won't run as is you don't have enough code. If use strict results in errors you have too little code (unless that is the issue).

How do you know when you have too much code? If there is a line, or even a character that you can remove and still show the problem you have too much code.

If the problem is not an IO problem, embed any required data in the code. One way to do this is to use a __DATA__ section to provide input data:

while (<DATA>)
    {
    print $_;
    }

__DATA__
Hello world
[download]

If you need some start state, ensure that you create it.

my @emoticons = (':P', '*tongue*');
[download]

If you really need an input file to show the problem, create one:

open outFile, ">", "test.txt";
print outFile <<END;
This is test data for reading by the example code.
END
close outFile;
[download]

If you need a 1G data base to show the issue, that's a problem. But chances are you can reproduce the problem with two modest size records, and supply them by creating a CSV file as shown above.

If you need to access a web page to reproduce the problem, use something that is likely to stay around for the life time of your node. The PM node itself is often a good choice!

When you post remember to use code tags and readmore tags. They won't affect your code, but may well affect the answers you get.

Remember to describe the output you expect to see. Best is to give a sample of what you get and a sample of what you want. Remember to actually run the code you are about to post to check it hasn't suffered bit rot since last you tried it. Copy & paste is your friend. Avoid retyping stuff you can just copy & paste, it's probably faster and certinally less likely to introduce typos.

Oh, and it seldom helps to describe your understanding of the nature of the problem - which sounds rather silly, but if you understood that, you wouldn't need our help would you? Concentrate instead on as suscinct a description of the symptoms of the problem as you can manage.

Oh, and remember to read Writeup Formatting Tips and What shortcuts can I use for linking to other information?. Remember also that if your indentation is crap people will give up on it - sometimes you just have to go with the flow (PerlTidy is your friend).

DWIM is Perl's answer to Gödel

Comment on I know what I mean. Why don't you? Select or Download Code

Replies are listed 'Best First'.
Re: I know what I mean. Why don't you? by xdg (Monsignor) on Nov 22, 2005 at 14:25 UTC
(You may fix the problem yourself this way, but don't consider that a failure - even if you don't get any XP :-).) Your post is wonderful advice, and yet, I wonder if the aside above isn't the crux of the issue? I'd imagine that if a would-be poster stopped to do these clarifying steps first, then 90% of the time the would-be poster could figure out the problem himself. The "challenge" for PM (if one wishes to see it that way) is that without all that effort, a problem posted to PM -- even poorly structured -- can usually get a decent answer. That aspect of PM is the dark side of the laziness and impatience principles at work -- why take a bunch of time to solve my problem myself when the community will do it for me? Fortunately, PM takes advantage of another principle, hubris, where the community races to solve even poorly phrased or trivial problems to clamor for the acclamation of their worth via XP. All of which is to say, yes, I appreciate the point of the post, but the people who read it and understand it and follow it aren't exactly going to be the same inexperienced posters who commit the original error, no? -xdg Code written by xdg and posted on PerlMonks is public domain. It is provided as is with no warranties, express or implied, of any kind. Posted code may not have been tested. Use of posted code is at your own risk.	[reply]
Re^2: I know what I mean. Why don't you? by QM (Parson) on Nov 22, 2005 at 17:20 UTC
All of which is to say, yes, I appreciate the point of the post, but the people who read it and understand it and follow it aren't exactly going to be the same inexperienced posters who commit the original error, no? Yes and no. If no one bothered to put effort into questions, I'd soon get frustrated at yet another awful SOWP post, and probably ditch PM after some interval. And if no one is here to answer those awful SOWPs (except perhaps for awful writers of similarly terrible SOWPs), little if anything of value would be here in the first place. Which, I suppose, would solve the awful SOWP post problem, as PM would not have a reputation for adding value, and would only have visitors lost in the ether. So yes, OPs like this are going to be missed by newcomers. One of our jobs as members of the PM community is to gently nudge newcomers with ways to be more effective here, and thus contribute more to the PM community, and get more out of it. But I'm not a diaper-changer kinda person. Sure, I can do the odd diaper, wipe the odd green nose. After all, that was me once upon a time, and someone was patient with me, and I'd like to do the same. But I'm not interested in a whole community of adults who can't find the toilet on their own. If one of them forgets himself, or comes from the 3 shells culture instead, for the sake of the Perl Monks Hazardous Waste and Diaper Detail, I'll point him to OPs like this. Some people just need to be told. -QM -- Quantum Mechanics: The dreams stuff is made of	[reply]
Re: I know what I mean. Why don't you? by Perl Mouse (Chaplain) on Nov 22, 2005 at 11:12 UTC
If there is a line, or even a character that you can remove and still show the problem you have too much code. Oh, yeah, sure. Golfing examples to show the unwanted behaviour! I seriously advice to not follow this advice to the letter. Else, you'll remove from your example an easy 2 lines and 25 characters, and are pelted by remarks you should use 'strict' and 'warnings'! Or in an effort to remove characters, you reduce your example to use single letter variables (without using my!) - and instead of people spotting your error, you'll get a ton of replies to use better variable names. Writing a short example is good - but don't golf. The example should be clear: it should only do what causes the problem, and it should be optimized for the reader. Which isn't the same as "write it in as little lines and characters as possible". `Perl --((8:>*`	[reply]
Re^2: I know what I mean. Why don't you? by herveus (Prior) on Nov 22, 2005 at 15:08 UTC
Howdy! I think you take GrandFather too literally. If the offending code runs the same with or without strictures/warnings, then they aren't essential to the code fragment. One can speak to strictures/warnings in the exposition. The key is to remove all distractions from the problem at hand. It's not a golfing thing. I think the recommendations are sound, especially if taken intelligently instead of mechanically. yours, Michael	[reply]
Re^3: I know what I mean. Why don't you? by Perl Mouse (Chaplain) on Nov 22, 2005 at 15:26 UTC
If the offending code runs the same with or without strictures/warnings, then they aren't essential to the code fragment. I know that, you know that. Unfortunally, it happens over and over again that someone posts a code fragment with a problem, without 'strict' or 'warnings', and where it doesn't matter whether strict and warnings are on or not, and people will reply with pointless posts saying "I don't know what the problem is, but it's better to use strict and warnings". That's why I recommend to not golf. It's a pre-filter, it keeps out some of the useless replies. One can speak to strictures/warnings in the exposition. Sure, but then you might as well say it in the code. The key is to remove all distractions from the problem at hand. Exactly. Remove all distractions from the readers. That includes not emitting things that might cause replies of the form "perhaps you should try adding this". The absense of 'use strict' or the use of '$a' is a trigger for people to respond. Not to the problem, but to the distraction. Add characters - to eliminate distractions. `Perl --((8:>*`	[reply]
Re^4: I know what I mean. Why don't you? by Aristotle (Chancellor) on Nov 24, 2005 at 01:04 UTC
Re^5: I know what I mean. Why don't you? by bigmacbear (Monk) on May 20, 2006 at 00:31 UTC
Some notes below your chosen depth have not been shown here
Re^2: I know what I mean. Why don't you? by GrandFather (Saint) on Nov 22, 2005 at 20:09 UTC
I agree with the golf comment and actually intended to make a comment along those lines, but forgot when it came to posting time. I'm sure anyone who actually follows the overall advise is unlikely to golf. DWIM is Perl's answer to Gödel	[reply]
Re: I know what I mean. Why don't you? by vagnerr (Prior) on Nov 22, 2005 at 12:33 UTC
(++) Well said Grandfather, There have ben many questions I simply havent asked because the process of creating a simple demonstration of the problem actualy demonstraited to me what I had done wrong in the first place (The Explain the problem to your pot plant solution). Its also worth pointing out that you might not be able to post the original code. If you are writing it comercialy there might be content that you just can't release. _______________________________________________________ Remember that amateurs built Noah's Ark. Professionals built the Titanic.	[reply]
Re^2: I know what I mean. Why don't you? by dragonchild (Archbishop) on Nov 22, 2005 at 15:01 UTC
This is also known as the "Teddy Bear" process, after a (possibly apocryphal) tale of a college computer center that required all students to explain their problem to the teddy bear on the lab monitor's desk before the lab monitor would listen to them. The tale goes that most of the time, the student would get halfway through their explanation and go "Ohhhh ...", blush, and walk away. My criteria for good software: Does it work? Can someone else come in, make a change, and be reasonably certain no bugs were introduced?	[reply]
Re^3: I know what I mean. Why don't you? by Moriarty (Abbot) on Nov 23, 2005 at 05:48 UTC
I have a penguin sitting on my monitor at work.	[reply]
Re^4: I know what I mean. Why don't you? by Madams (Pilgrim) on Nov 26, 2005 at 05:21 UTC
Re: I know what I mean. Why don't you? by Spidy (Chaplain) on Nov 22, 2005 at 17:09 UTC
++ Grandfather, You've pointed out perfectly the issues that I always have when debugging my code and attempting to put it up here. Usually when I'm chopping it down to a couple lines to reproduce the error, it all gets fixed up anyways. My Website Get Eated!	[reply]
Re: I know what I mean. Why don't you? by Anonymous Monk on Nov 22, 2005 at 14:17 UTC
Read How (Not) To Ask A Question, a Tutorial by jeffa.	[reply]
Re: I know what I mean. Why don't you? by spiritway (Vicar) on Nov 23, 2005 at 05:59 UTC
Well said, GrandFather! One of the great benefits of PerlMonks is being able to ask for help - and feeling a need to simplify the problem as much as possible. I almost always wind up answering my own question, because in the process of simplifying, I isolate the problem and can identify it easily. For every one of my questions that makes it to SoPW, there are dozens that don't get past the part where I'm explaining the problem.	[reply]

Back to Meditations