Skip to main content

Build a minimal, complete, reproducible example

This step is what most people don’t do well in their questions that involve code, and is arguably the most important part of the process of asking a good question. Stack Overflow already has some advice on this, which you should read thoroughly. We won’t repeat that here, but it's worth noting that many questions are downvoted and closed on a daily basis because the asker didn’t take the time for this step. Here are the brief descriptions of each key attribute taken from Stack Overflow:

  • Minimal: Use as little code as possible that still produces the same problem.
  • Complete: Provide all information someone else needs to reproduce your problem in the question itself.
  • Reproducible: Test the code you're about to provide to make sure it reproduces the problem.

There are several key reasons why it’s important for your code to have each of the above qualities.


Sometimes we see questions with hundreds of lines of code with no indication where the problem is. This is off-putting to people who might be interested in solving the problem because it’s asking them to read and understand far more code than is necessary to understand the issue. You should remove any code that’s not directly contributing to the unexpected behavior, reducing the amount of work required by the reader.

The code you show should be as easy as possible to read and understand, and shorter is always easier (assuming it is also complete).

Imagine you are writing code that performs three tasks:

  1. Query a database
  2. Perform some calculations on the returned data
  3. Render the results on screen

In total, this could be hundreds of lines of code! If you're observing a problem with it, you should narrow the problem down to just one of the three tasks, and show only that relevant code, explaining what you observe when running it. As much as you can:

  • Isolate the problematic code into its own source file or function.
  • Do as much debugging as you can on the isolated code before you post the question.
  • Don’t show any lines of code that are not directly responsible for the unexpected behavior.


Providing complete code is sometimes in conflict with “minimal” above, but just as important. It’s often the case that the observed problem with some code is actually rooted in other code not shown at all, and you haven’t debugged the problem well enough to understand what that is.

Ensure that:

  • The values of all variables are stated in the question (or better, hard coded).
  • All invoked functions are present (or explained)
  • Any error messages you observe are present, accurate, and complete. You should copy and paste the entire error message and stack trace into your question, rather than typing a part of it by hand.

Without complete code, it might not be possible for the reader to duplicate the behavior and understand what’s going wrong. This runs the risk of the reader skipping your question entirely, or voting to close it due to lack of details. Even if the reader is willing to investigate, you will likely have to spend time going back and forth with them in comments to figure out what’s missing.

Your question will get answered more quickly if you spend time to ensure that what you present in the question is complete and requires no additional information to understand the issue.


Once you have complete, minimal code that demonstrates the problem, you should include enough information to allow others to observe the same thing on their own. Don’t just paste your code into the question and leave it. You should also do the following three things.

1. Provide instructions

State exactly what you did to run the code. Include any command line programs, setup instructions, and configurations that you’re using. The reader should be able to reproduce the issue based on the information you provide. Don’t assume that they know how you do your work - tell them how. The problem could be with your procedure rather than the code itself, but no one will be able to know this if you don’t share that information.

2. State your observations

When you run the code, state clearly what you are observing. This helps the reader understand how you know there is a problem. To illustrate the problem at hand, it’s best to add logging statements to your code, and share the contents of that log in your question. If you are doing step-through debugging, explain or show what you see in the debugger where things are going wrong.

3. Explain how your observations are different than your expectations

This is the key step. The only way that code can appear broken is if it does something other than what the author intended. The reader must understand what you expect the code to do in order to know best to respond. Many times, the code you write actually works exactly as it should, but your expectations of it are inaccurate. The solution to your problem might just be a matter of understanding how some code or API actually works in practice, and changing your strategy to use it correctly.

Breaking this down into individual steps that you can use to write your question:

  1. What did you observe when running the code?
  2. What did you expect to see that’s different from what you observed?
  3. Why is #2 the correct result (or the better result)?

Why is all this important?

There is no doubt that it’s time-consuming to build a minimal, complete, reproducible example, but we can confidently say that it’s worthwhile. If you don’t do this, you are likely to be asked to do it in a comment. And if you do put in this effort, you are also likely to solve your own problem. Building minimal, complete, reproducible examples is how experienced developers isolate problems for debugging. If you can learn how to do this, you will become a better programmer, in addition to making your question easier to answer.