24

I frequently ask for help with my programming projects on SO. I'm still not particularly comfortable around the community, so I try to keep my questions as concise and on the point as possible so I'm not wasting anyone's time, but I think I précis too far and don't provide enough detail. Where does the balance between too little and too much lie? What do you want to know?

If I'm writing application x and function y is ballsing up, do you want me to tell you what the app is for, what platform it's on, what language, who it's for, etc., or should I just post the code for function y? Should I show you the tests I did that prove I'm having a problem, or are you content to accept on faith that something isn't working?

Of course, the details would vary from problem to problem, but I'm hoping someone can provide a basic checklist of what I should be including in my questions.

15
  • 19
    Ideally, all information needed for someone to reproduce the problem would be nice (though not always possible) , as well as what you've done to try to solve the problem. The checklist you're looking for has actually already been written by Jon Skeet here
    – awksp
    Jul 23, 2014 at 18:51
  • 1
    Nice, thank you for the link. I like the idea of rubber duck debugging :).
    – Lou
    Jul 23, 2014 at 18:52
  • 13
    Take a step back and look at the problem from the outside. I know that sounds crazy, but picture what someone from the outside would see and do to solve your problem. A lot of times this will help you solve your own problem, and if not, give you a better perspective of what others will want.
    – Kevin B
    Jul 23, 2014 at 18:53
  • Good description here
    – geocodezip
    Jul 24, 2014 at 2:27
  • 3
    Much of what you're asking is answered on the help page. See How to create a Minimal, Complete, and Verifiable example.
    – mason
    Jul 24, 2014 at 3:01
  • 3
    Skeet doesn't need a checklist. He often seems to be able to read into the minds of the OP and post an answer. It'd be nice if he starts to update the questions too after posting answers based on interpretation and assumptions.
    – devnull
    Jul 24, 2014 at 3:31
  • 1
    @KevinB, you speak the truth. I've often started a question here only to abandon it upon solving my own problem trying to anticipate the questions someone else would ask in order to help me.
    – Jason
    Jul 24, 2014 at 19:24
  • 2
    I want to know everything about the problem. I don't want to know anything about stuff that's not the problem. Your application x isn't the problem, and most of function y isn't the problem either. That's why you should create a complete, minimal, verifiable example separate from your application and your earlier function that reproduces the problem. Rather than asking "how much do you want to know," ask "how much don't you need to know?" That usually means reproducing the problem outside of its original environment, but you'll have stripped away a whole lot that we don't need to know. Jul 24, 2014 at 19:32
  • 1
    What your application is and does is probably the least relevant. You should try to, as much as possible, take the problem out of the project completely. Isolate it to the smallest possible sample that reproduces the problem. Many times, this process either leads you to the answer, or makes you realize that the problem isn't what you thought it was. By the time you're ready to click "post" on a question, it is very unlikely that your application is even in the picture anymore. Jul 24, 2014 at 19:42
  • I'm glad several people have brought this point to my attention, I was placing more importance on the development environment than the problem. This is good to know when writing questions.
    – Lou
    Jul 24, 2014 at 19:47
  • Try to make the beginning insteresting & inviting enough for the others to spare you a minute or two. You won't get five, just for reading about your problem.
    – TaW
    Jul 24, 2014 at 20:14
  • @TaW - Sorry, I don't understand your second sentence. Also, I was under the impression SO prefer direct and to-the-point than interesting and inviting, but maybe other users will put me wrong.
    – Lou
    Jul 24, 2014 at 20:18
  • 'direct and to-the-point' and 'interesting and inviting' should not be seen as opposites, on the contrary! I meant that we need some reason to read for more than a minute or two. If this reason is there but two pages down most will miss it.
    – TaW
    Jul 24, 2014 at 20:29
  • @LeoKing TaW's second sentence references the first. You want "others to spare you a minute or two [of their time to look at the question]". To get them to do that, it needs to be interesting and inviting. "You won't get [them to spend] five [minutes] … [to read about] your problem." Jul 24, 2014 at 21:37
  • ALL the things? Even the Alot?
    – Lou
    Jul 25, 2014 at 19:28

7 Answers 7

28

I need to know just a handful of things:

  • What you've done to get yourself in the state that you're in,
  • What your inputs have been to get the output that you're seeing, and
  • What your desired outcome is.

I don't need much background for what it is you're doing or what it is you're trying to solve (unless it feels like an XY problem - then I'll pry more for it), and I don't want just a block of code that says, "It's broken."

Giving someone the ability to replicate the state that you're in is ideal. It helps get you an answer much faster, as one could simply copy and paste the code into their IDE of choice and see the same thing you're seeing.

4
  • 7
    Okay. I guess my main concern is that I don't want to make people have to ask for more details, but that seems silly in retrospect. So, to sum up: reproducibility is key here?
    – Lou
    Jul 23, 2014 at 18:57
  • 16
    Yes, the problem being reproducible is a huge part of debugging. If you can reproduce the problem with a very small subset of the code, it's likely you will be able to find the problem yourself through the process of elimination. you can then begin looking for ways to solve the problem.
    – Kevin B
    Jul 23, 2014 at 18:59
  • 3
    and if you don't find it yourself but reduced it to the shortest and cleanest example possible, someone else needs far less effort to thoroughly check your code and test it life, so is orders of magnitude more likely to do so, and do so successfully. Jul 23, 2014 at 19:04
  • 10
    Step 1 of any debugging adventure should be to identify the problem. If you can't identify the problem, you can't be sure that you have solved it once it goes away; all you can do is fight the symptoms. Being able to effectively reproduce it and then make it go away by eliminating code will immediately point you to a narrow area where the actual problem is.
    – Kevin B
    Jul 23, 2014 at 19:07
11

Ideally you want to make it as easy as possible for people to understand an answer your question.

You should try to find a balance between providing the important information, and making your question easy to read. The more information that you provide, the more difficult it is for a potential answerer to digest that information and filter out the unimportant stuff.

I know that this might be hard for someone who doesn't quite know what to look for, but try to put yourself in an answerer's shoes, and do the best that you can.

Remember, it's okay if people are still asking you questions so long as you're responsive to those questions. We don't expect you to write a perfect question the first time. But we do expect you to be responsive and involved.


I also like to push the SSCCE Short, Self Contained, Correct (Compilable), Example

I like to define an SSCCE to be "the minimum program such that if you could fix the problem in that program, you could fix the problem in your actual program".

Not only does an SSCCE allow people to copy and run your code through the debugger with minimal effort, but it's also helpful if you don't want to post your actual production code on the internet.

3
  • Unfortunately, it seems that these days anything correct gets shoved over to Code Review. I can't for the life of me understand the point of splitting the community like that.
    – dfeuer
    Jul 24, 2014 at 3:02
  • @dfeuer, because evaluating the (importantly: subjective) best way to improve code requires: a different skill set, a different mindset, and a different attitude then helping solve broken code that has a very finite set of valid answers.
    – Kirk Woll
    Jul 24, 2014 at 3:51
  • "I consider an SSCCE to be" That's not only what you consider, that's just what it is :|
    – BartoszKP
    Jul 24, 2014 at 19:49
5

"If I'm writing application x and function y is ballsing up, do you want me to tell you what the app is for, what platform it's on, what language, who it's for, etc., or should I just post the code for function y?"

I don't want "function y", or any part of your application. What I want to see is a short, clean, stand-alone piece of code that I can run to observe the problem.

I also want to know what the code is supposed to do, and what it does for you (since that might not always be what it does for me). If your code requires some data to demonstrate the problem, please provide the data too, in whatever format is most easily copied.

I don't necessarily need the standard boilerplate for your language (you don't have to include the <?php before every piece of PHP code, for example, and I'm perfectly capable of wrapping C code inside int main (int argc, char *argv[]) { ... }), but I'd rather not deal with something that requires a bunch of vaguely described and hard-to-install libraries or frameworks just to run.

Where applicable, a JSFiddle / SQLFiddle / Ideone / CodePad demo is always nice. But keep it simple, please! Just because you can paste 500 lines of code into Ideone doesn't mean anyone wants to read it.


The main exception to "just a simple stand-alone example, please" is when the first reaction I have, upon seeing your question, is "why would you want to do that in the first place?" In that case, I do want to see some explanation of what you're really trying to accomplish, so that I can tell if you're having an X/Y problem.

Similarly, if (something very much like) your question has been asked before, but the earlier answers (or the standard answer to problems of that type) don't work for you, I do want to hear why, so that I can tell what alternative solutions might work.

In either case, don't go into too much detail, at least unless specifically asked. A simple "the reason why I want to write a text editor in brainf*ck is because (it's a challenge / my boss told me to / I accidentally changed my shell to bf.exe / etc.)" will do. You'll probably still get answers questioning your choice and suggesting alternative methods (that's what X/Y problems are about), but at least they'll be informed suggestions.

1
  • 2
    one quibble, I do want to see " the standard boilerplate" parts. In NET, it is often important to know whether the code executes from some called procedure or whether the OP is trying to fire queries from the MouseMove event. Jul 23, 2014 at 23:34
4

I want to know everything about the problem. I don't want to know anything about anything that's not the problem.

Your application x and most of your function y aren't relevant. They don't (usually) have anything to do with the problem; they're just an environment where the problem happened to appear. The same problem also appears in a much smaller application, and in a much smaller function, and that's what you should show us in the question.

That does usually mean a bit more work before you post a question, because you'll be paring your code down to the minimal program that still demonstrates the problem, or you'll be starting from scratch, reconstructing just enough of a program to demonstrate the problem. It can sometimes be a lot of work, but you'll often find a solution in the process, so won't need to write the question at all. (Or, you could still write the question but also write an answer, too!) It's important, though, because other people may have the same problem, but they won't be writing your application x or your function y. Those things will just be noise when they're looking for a solution to the same problem. They end up being noise to people trying to answer your question too.

  • Rather than asking what we need to know, ask yourself what we don't need to know, and then prove it by reproducing the problem in a smaller program that removes the stuff that we don't need to know. Once you can't do that anymore, you've determined, by a process of elimination, what we do need to know.

  • Rather than asking how much of your code we need, pretend that you're not allowed to show us any of your code. (This might well be realistic, if you're a professional programmer and can't show your client's code.) Then what code can you ask about? You can ask about new code that has the same problem. You don't want to spend any more time than necessary writing that new code, so keep it as short as possible, but still demonstrating the problem.

I think that these guidelines point to what might be present in an ideal question. As some of the comments point out, it's not always quite so clear cut. Sometimes it can be hard to pin down what exactly is happening, and whether it depends on some external factor, or something else. Going though this process, though, will help you narrow down what it could be and what it probably isn't, and if you walk through this process in earnest, the question will be better than a code drop asking "where's the bug?" Most users will recognize the effort and you, having gone through the process, will be better prepared to field questions and comments asking for clarification.

15
  • 1
    This one surprised me. I would've thought the environmental information would be useful. Doesn't it makes a difference whether I'm running Python 3.0 or 2.7, or if the PHP script is using POST or GET, etc?
    – Lou
    Jul 24, 2014 at 19:44
  • 1
    That's a bit simplistic, most askers don't necessarily know what is related or has nothing to do with the problem. They can have a rough idea, but sometimes the devil is in the detail, and problems also often arise due to external factors.
    – Bruno
    Jul 24, 2014 at 19:45
  • @LeoKing Environmental information is important. I don't think my answer here would exclude it. If an asker has access to different environments and can test it in them, then they can say "this is reproducible in versions X, Y, and Z," that's useful. If they don't have access to different versions, then they should say "I'm using version X." That is information that answerers need because it may well be part of the problem. Jul 24, 2014 at 19:50
  • @Bruno A minimal example isn't necessarily a small example, though it should usually tend toward the smaller side. You're right, though, that it's not always apparent what bits are related and what aren't, but that's why reconstructing from scratch can be so important. If you from scratch with one line of code, and still see the problem, great. If not, add another line. If the problem comes back, great, but it's important to check if it remains if the first line is omitted (e.g., was it the combination of the two lines, or just the second line that was added?). Jul 24, 2014 at 19:53
  • Your answer does seem to completely discount the code environment, when you say "I don't want to know anything about anything that's not the problem."
    – Lou
    Jul 24, 2014 at 19:54
  • I'm just picking holes though, everything else you say makes sense.
    – Lou
    Jul 24, 2014 at 19:55
  • 2
    @LeoKing if the code environment isn't the problem, then I don't want to know anything about it. If the same C code exhibits the same segfault regardless of what compiler is used, then I don't care much about the compiler. If it only happens with one compiler, but its fine with others, then it is relevant to the problem and should be included. In any case, the environment is part of what a potential answerer needs to know in order to reproduce the problem. You could make a parallel claim that we wouldn't want to know what language the code is in, but clearly we do; it's relevant. Jul 24, 2014 at 19:59
  • Ah, okay, then I see what you mean.
    – Lou
    Jul 24, 2014 at 20:00
  • @JoshuaTaylor Sure, but it depends very much on what you're programming and how much it interacts with elements outside your control. Taking this question I've just answered for example. In most cases, it would make sense for users to anonymise the error (making the question more generic), but luckily, this user didn't in this case and left the actual "issuer by". That little detail gave a strong clue regarding an unusual environment, which led to an answer very different from a more traditional one that could be written for this exception.
    – Bruno
    Jul 24, 2014 at 20:00
  • 1
    @Bruno Of course these are just sort of general guidelines, and any real case may well depart on some bits or others, but ideally that user would have tested that code inside and outside of the network, and found that the environment is relevant, as the behavior wasn't reproducible outside of that network. That's not always feasible, of course. The point is that in a question about code (which that one wasn't, I'll note) a user should try to show the least amount necessary to reproduce a problem. Jul 24, 2014 at 20:06
  • @JoshuaTaylor I think you're right. The problems come when some reviewers take these guidelines too strictly and start downvoting or voting to close just because the question doesn't fit the checklist. (This seems to have become worse over the past few months.) For this particular problem, someone with enough experience would know the issue without needing to see a single line of code, and any extra coding attempt to fix the problem would almost certainly have introduced a security vulnerability instead.
    – Bruno
    Jul 24, 2014 at 20:11
  • 1
    @Bruno I think that some of the reason for downvotes (this doesn't explain an increase, of course), is that many users don't seem to grasp the importance of telling us the things that they've tried in trying to simplify the problem, even if it didn't end up being helpful, or the things that they would have liked to, but couldn't try. E.g., someone asks, "I'm trying to use method X to do Y, but I get this error Z," gets a response "the typical way to do that is with method X', not X," and replies "but I already tried X' and it didn't work because Z'." It turns out… Jul 24, 2014 at 20:15
  • 1
    … that Z' reveals the underlying problem, but the user didn't tell us what they'd tried while trying to simplify the problem. Jul 24, 2014 at 20:16
  • Oh absolutely, but you're looking at it from a "troubleshooting" point of view, whereas the site claims to build a "repository of knowledge". As an answerer I much prefer to get the details indeed, otherwise you can't help, but somehow this seems partly incompatible with that idea of more generic knowledge base that aims to build canonical or at least vastly re-usable questions (as talked about in this question). There's a tension between the two objectives that I'm not sure some more curator-oriented users are acknowledging.
    – Bruno
    Jul 24, 2014 at 20:22
  • @Bruno +1 on that answer, especially for "This is all a very fine balancing act". Jul 24, 2014 at 20:24
2

I try to create a test case on ideone.com. This allows me to really break down the function / section of code that is crapping out and escape the mindset of the current project that I'm working on.

Pasting the function / a stripped down version is handy, and details of the real crux of the problem. Of course, language is important, as to what it's doing and what you want it to do.

Keep the description concise and problem focused on one, or a few narrow problems.

0

In addition...

If you are writing in a programming language that has exception handling, I want to see the exact text of that exception. That includes all the information from the exception object--the exception type, the message, and the stack trace of the exception and every inner exception, depending on implementation.

If you take a screenshot of the exception message, you will be thrown from the train. If you only provide part of the full load of data the exception carries, you will be whipped and rubbed with lemon slices. And if you provide these details and we SEE the answer is OBVIOUS by reading the plain text of the exception...

enter image description here

3
  • 1
    Downvoter, care to comment? (Yes, trolling)
    – user1228
    Jul 23, 2014 at 19:50
  • 3
    Nice downvote magnet. Made me laugh, though. Jul 23, 2014 at 23:31
  • This tells you succinctly what all is required.
    – devnull
    Jul 24, 2014 at 3:29
0

If this is for a runtime error, at a minimum:

  1. The complete runtime error message (if a runtime error was flagged)
  2. The "exception traceback" or "call stack" or whatever for the runtime error (at least the top-most 10 or so entries)
  3. Code covering the section where the error occurred, with the failing line identified somehow
  4. Declarations for the variables used in that code section
  5. Inputs -- the initial state of the variables leading into the failure
  6. Outputs -- any output/final state that is relevant (and match inputs and outputs -- don't give inputs for case A and outputs for an entirely different case)
  7. A description of what you've done to debug the problem so far

Of course, the odd thing is that if you collect this info you will quite often solve the problem yourself before you get around to asking the question.

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .