How to create a Minimal, Reproducible Example
When asking for help with code that is not working, people will be better able to provide help if you provide code that they can easily understand and use to reproduce the problem. This is referred to by community members as creating a minimal, reproducible example ( reprex ), a minimal, complete and verifiable example ( mcve ), or a minimal, workable example ( mwe ). Regardless of how it’s communicated to you, it boils down to ensuring your code that reproduces the problem follows the following guidelines:
Your code examples should be…
- …Minimal – Use as little code as possible that still produces the same problem
- …Complete – Provide all parts someone else needs to reproduce your problem in the post itself
- …Reproducible – Test the code you’re about to provide to make sure it reproduces the problem
The rest of this help article provides guidance on these aspects of writing a minimal, reproducible example.
Minimal
The more code there is to go through, the less likely people can find your problem. Streamline your example in one of two ways:
- Restart from scratch. Create a new program, adding in only what is needed to see the problem. Use simple, descriptive names for functions and variables – don’t copy the names you’re using in your existing code.
- Divide and conquer. If you’re not sure what the source of the problem is, start removing code a bit at a time until the problem disappears – then add the last part back.
Minimal and readable
Don’t sacrifice clarity for brevity when creating a minimal example. Use consistent naming and indentation, and include code comments if needed. Use your code editor’s shortcut for formatting code. Also, use spaces instead of tabs – tabs might not get correctly formatted.
Complete
Make sure all information necessary to reproduce the problem is included in the post itself:
- If the problem requires some Bash script as well as some Prolog, include code for both . If a problem requires some C++, some SQL, and some Prolog, include code for all three. The problem might not be in the code that you think it is in.
- Use individual code blocks for each file or snippet you include. Provide a description for the purpose of each block.
- Post the code in SWISH if practical and add a link in the post. Note: SWISH limits what can run, e.g. sandbox restrictions (section 5.7 Sandboxing queries).
- DO NOT use images of code. Copy the actual text from your code editor, paste it into the post, then format it as code. This helps others more easily read and test your code.
- Unit Test Include unit test if you know what the results should be. Test cases should include both cases that work and cases that do not work.
- Homework If this is a homework problem then include the instructions, as text not as an image, of the problem. If you are not allowed to ask for online help with homework then don’t.
Reproducible
To help you solve your problem, others will need to verify that it exists:
- Describe the problem. “It doesn’t work” isn’t descriptive enough to help people understand your problem. Instead, tell other readers what the expected behavior should be. Tell other readers what the exact wording of the error message is, and which line of code is producing it. Use a brief but descriptive summary of your problem as the title of your post.
- Eliminate any issues that aren’t relevant to the problem. If your post isn’t about a compiler error, ensure that there are no compile-time errors. Use a predicate such as check/0 to validate the Prolog.
- Double-check that your example reproduces the problem! If you inadvertently fixed the problem while composing the example but didn’t test it again, you’d want to know that before asking someone else to help.
- Mind reading We can not read minds so don’t take for granted something. In helping beginners a common problem is that something was not stated that they took for granted was known. If the rubber duck doesn’t know it we don’t know it.
It might help to shut the system down and restart it, or transport the example to a fresh environment to confirm it really does provide an example of the problem.
Specifics of software and environment
Always include the version of SWI-Prolog which is noted in the top-level, e.g.
Welcome to SWI-Prolog (threaded, 64 bits, version 8.1.21)
If the code interacts with the OS, then include the specifics of the OS.
If you installed a Prolog package then include the specifics of the package, where did you get it, how did you install it.
If the code uses an interface to another programming language such as Java, .Net or Python include the version of the code.
If the code is using command line options during startup, include the command line.
If the code changes a file such as init.pl then include it.
If it uses a Prolog flag, then list the flags, e.g. run current_prolog_flag(Flag,Value).
Formatting
Make use of markdown to format the post. Reading unformatted post is not enjoyable.
Checking post
Before clicking to post, using just the information from the post and starting with a clean work environment e.g. starting a new instance of SWI-Prolog and/or creating empty files to hold the source code, etc., do what any user would do reading the post to try and recreate your problem by copying code, running commands, etc. as noted only in the post. Remember that you are asking for help and should do as much work as possible to make it easy for those helping you including double checking your post.
Bug hunting toolbox
While the toolbox page is still a work in progress, there are many ideas of value that can be found in the Bug hunting toolbox to help you find and fix the bug before posting a question.
The above is based on a StackOverflow version.
User contributions licensed under cc by-sa 4.0 with attribution required.