What do we mean by a self-contained (minimal) working example?

Question

Szabolcs linked to this page titled "Short, Self Contained, Correct (Compilable), Example" recently, and it really is well written. But not everything there applies to Stack Exchange, and even more so to the Mathematica SE.

Can we write a set of guidelines more tailored to this site, and since this is a meta site anyway, could we come up with minimal examples of a post that does and a post that doesn't follow this guideline?

This would allow us to link to this answer in the future.

Answer 1

IMO, best answered by the community. My attempt is primarily so we aren't starting from a blank slate.

---

Guidelines for helping others help you with your code ordered according to importance for reproducibility and attracting help.

1. Try to focus in on the issue. Do not copy all the contents of your notebook. Do not try to explain all the irrelevant parts. Keep it to the minimum, with emphasis on that the issue is reproducible by you and others.
2. Provide definitions. Make sure that all your symbols and functions have their definitions provided in your code snippet. Can others reproduce your problem with the provided code or did you miss something?
3. Verify your example and its reproducibility. Before posting your question, copy and paste your example into a notebook (preferably with a fresh kernel). Does executing the code demonstrate the problem you're having?
4. Try to minimize your copied code and its input and output.
   • Avoid posting a wall of code. The larger your code grows the higher the probability for additional errors is. By reducing the extraneous code in preparation for asking a question (for example fancy plot labels which have nothing to do with the main issue), you attract more helpers, and perhaps you might find the problem yourself.
   • Keep dataset sizes reasonable. Do you have a symbol with one thousand data points? Is the length of the dataset significant to the problem? If not, then cut it down. Try to come up with the smallest subset of your data that still exhibits your problem.
   • Do not include all your (intermediary) results. Only include output that is relevant for the issue. It is unnecessary to upload all your plot results or a huge list of coordinates just because they are all pinked out.
5. Get rid of formatting. 2D typesetting and greek letters look cool, but don't contribute to the clarity of your question. Most people will be put off by having to read through obscure code or to do a double take to interpret it. If you insist on formatting, use the code formatting tool in the editor (curly brackets).

Users who make an effort to incorporate these guidelines into their example code writing will not only benefit from higher response rates, but the community will undoubtedly reward you with a few up-votes for your efforts to make Mathematica.SE a clean-looking site.

Answer 2

Why and how to construct a minimal example? – A case study

Let us look at a recently posted question as an example. The question, as originally posted, did not have a complete example.

The definitions of functions like beta were not shown.

Thus people could not run this code, and could not see the error on their own computers.

Always make your example code complete. Make sure that when you copy the code to a new notebook, and run it, it illustrates the problem you are asking about.

When the asker of the question was told to make it complete, he posted an extremely long notebook. This is just part of it:

Would you read through so much code to find someone's mistake? Most people wouldn't. This is why it is important to make the example code minimal.

Always make your example code as short as possible. Localize the problem yourself, do not expect others to do it for you!

Creating a minimal example, or localizing the problem, is usually very straightforward. However, it may be very time-consuming. Please do it on your own before asking a question on StackExchange.

How to localize the problem?

Simply keep removing parts of the code that seem irrelevant. Remove some, then check if the problem disappeared. Keep repeating until you find the bit of code that caused the problem.

Let us use the notebook from the linked post as an example. This is the part that causes the error:

Is Animate necessary to trigger the error? Are you not certain? Remove it to test! In this case the error was still there. In fact it was quite clear from the error message that the error was in Show, not Animate.

Show came from the FG[s] function above. The function definition can be dropped, and we can look at Show alone.

Then we end up with a long Show expression of the form

Show[
  a, b, c, ...,
  PlotRange -> ..., ImageSize -> ...
]

Remove a, b, c, etc. one by one and see which one makes the error go away. Each of a, b, c, ... depends on several previous definitions in the notebook. Thus removing them can hugely reduce the size of a complete example.

In this case, it turned out to be the PlotRange option, which did not even depend on the several pages of code that was also included in the notebook. The error was caused by a single line only, which was quite straightforward to find, and could have illustrated the problem alone.

Furthermore, it turned out that this line was not written in the same way in the original post as in the notebook.

The example code in the original question was useless because:

• it was not complete
• it was not identical to the notebook
• it was unnecessarily long

Most importantly, people could not simply copy it into their own notebook and see the error for themselves.

Please do not commit these mistakes and maximize your chances of getting an answer. Always post example code that is complete, minimal (as short as possible), and illustrates the problem clearly.