20

I rarely link to the MRE page to an experienced programmer (even if that happens from time to time), so I think it's important that the page is as concise and simple as possible. Shortening it will also encourage people to read it through as longer texts require a larger time investment and might turn some people away. Of course, important information shouldn't be sacrificed for brevity.

Here is the link to the page.

I'll quote some of the text I think is problematic and suggest fixes as best as I can.

"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)"

These different names just take up much unnecessary space. It is rarely important to know the different linguistics community members are using, especially when all [mcve] comments are translated to [mre] anyway. What's important is how you create a good example.

My suggestion would be to change this to:

This is referred to as creating a minimal, reproducible example. Other names may occur (see footnote).

This seems reasonable as there is already a footnote explaining different terms used.

"Regardless of how it's communicated to you, it boils down to ensuring your code that reproduces the problem follows the following guidelines:"

This is just unnecessary noise... My suggestion:

This is to ensure your code is following the guidelines:

The bullet-point summary is quite good:

  • …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 question itself
  • …Reproducible – Test the code you're about to provide to make sure it reproduces the problem

My only problems are that the dots before each word seem out of place. It looks unconventional and doesn't provide anything. Also, I think "Test" should be in bold.

"The rest of this help article provides guidance on these aspects of writing a minimal, reproducible example"

You don't need to say what's coming next. It's obvious from the titles. Remove this sentence completely.

"The more code there is to go through, the less likely people can find your problem"

This is one of two times where I think we should elaborate more. The sentence makes it seem that the problem is solely that the user might not get an answer when it is in fact a way for the answerers to not have to go through hundreds of lines of code. That should be emphasized.

Maybe something in line with:

The more code there is to go through, the more time it takes users to find your problem and the less likely they are to find it.

"Use simple, descriptive names for functions and variables – don’t copy the names you’re using in your existing code"

This is misguiding. I think it's okay to use names from existing code, as long they're simple and descriptive names. So much of this is redundant. You just need to have:

Use simple, descriptive names for functions and variables.

"Also, use spaces instead of tabs – tabs might not get correctly formatted on Stack Overflow"

Is this still necessary? I always use tabs and SO should handle this properly by now. I'd suggest removing it and fixing any problems that may occur from not including this line on the page.

"If the problem requires some server-side code as well as some XML-based configuration, include code for both. If a web page problem requires HTML, some JavaScript, and a stylesheet, include code for all three."

This example is way too complicated and specialized for someone who doesn't know how to write an MRE. My suggestion would be something along these lines:

If the problem requires both code and a file, include both the code and the contents of the file. And if it involves an image also, then include it as well.

"Use Stack Snippets to include runnable HTML, JavaScript, or CSS."

This is only for javascript and is not necessary for a huge majority of people. Most users write in different languages and even the people who write in Javascript might not have enough for Stack snippets to be applicable since they are using a backend. I'd suggest removing this completely or, as suggested in the comment section, recommend checking the language-specific tag for language-specific steps to post code.

"This helps others more easily read and test your code."

This is the second time I'd argue for more elaboration. Images in code have more problems than this. It might not be necessary to list them all here, but something like this would be nice:

This helps others more easily read and test your code, and helps with many other problems.

"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."

A small change, but replace this with a comma.

Instead, tell other readers what the expected behavior should be, what the exact wording of the error message is, and which line of code is producing it.

"If your question isn’t about a compiler error, ensure that there are no compile-time errors."

Remove the mention of a compiler. It makes it easier for people who don't know what a compiler is, and an error can exist without it being a compile error. It'll make sense either way without the risk of confusion.

"Use a program such as JSLint to validate interpreted languages. Validate any HTML or XML."

Again with web programming. This is not a majority of the users. Be more general.

"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."

I think this is could be simplified by just saying:

Always test your code before posting to verify it still exhibits the same problem you're asking about.


These are some suggestions I think would greatly improve the MRE page.

11
  • 1
    re: removal of Stack Snippets section. How about recommending instead to check the language-specific tag for language-specific steps to post code? The [[javascript]](stackoverflow.com/tags/javascript/info) tag already has that info about stack snippets, JSLint, etc. Haven't checked all the other major language tags, but at least each tag can hold their own guidance, instead of the MRE page. Commented Feb 20, 2022 at 22:33
  • @GinoMempin Definitely a good suggestion! I think I'll add it! Commented Feb 20, 2022 at 22:50
  • 6
    I think my biggest concern is this: "If the problem requires some server-side code as well as some XML-based configuration, include code for both. If a web page problem requires HTML, some JavaScript, and a stylesheet, include code for all three." There are so many technical and area-specific words that it makes it pretty much useless for most people who are visiting this page. A general page should be general. Commented Feb 20, 2022 at 23:16
  • 2
    I doubt most users are even aware of the existence of the [mre] and [mcve] tags.
    – Lundin
    Commented Feb 21, 2022 at 11:12
  • 2
    "don’t copy the names you’re using in your existing code" This text needs to go. One of the most common reasons that questions get closed for lacking a reproducible example is that poster wrote down some strange artificial example for the benefit of SO instead of copying the actual code. But their example doesn't match compiler errors etc and might not even contain the problem.
    – Lundin
    Commented Feb 21, 2022 at 11:15
  • 1
    @Lundin My point was that users linking people to the MRE page will use either of those tags, but they both translate to [mre]. So it's not often that the other terms come up. Commented Feb 21, 2022 at 11:31
  • 1
    If people indeed don't know about the [mre] shortcut, perhaps adding a note to the MRE help page would be useful? Commented Feb 21, 2022 at 15:48
  • 2
    The help page wouldn't necessarily help me remember that it exists. The only thing that would would be a list of such shortcuts existing under the comment box... but a bunch of abbreviations without explanation would only be useful to those who can interpret them.
    – Kevin B
    Commented Feb 21, 2022 at 15:52
  • 5
    “see footnote” — Related: Min-Reprex, MCVE vs. MVCE. “checking the language-specific tag for language-specific steps to post code” — But that’s even more text for users to ignore! But seriously, this is good advice, however, tag wikis should be more discoverable in general and be updated regularly. Related: Tag-specific MRE page. Instead of linking to the idownvotedbecau.se site, maybe link to this FAQ? Also “JSLint” → “linters”, and remove “interpreted”… Commented Feb 22, 2022 at 14:25
  • 1
    I think under "reproducible" it would help to be explicit that somebody else should be able to copy&paste the code from your question, run it, and see the same result or error that is described in the question.
    – kaya3
    Commented Feb 24, 2022 at 18:18
  • 1
    I personally find it very unfortunate that the page in its current form mentions several different acronyms but fails to refer to the one that represents what's in the page title and URL - MRE. Commented Jun 1, 2022 at 22:11

1 Answer 1

3

Given the feedback and the votes, I'd consider this an overall improvement over the current version. This edit reduces the current page with approximately 100 words, but still gives more useful and general information.

Below is what I suggest the page should look like, with the help of feedback from the comments and from other questions. It's clearer, more consice and more understandable to a generic user.

For context, here's the current version: https://stackoverflow.com/help/minimal-reproducible-example


How to create a Minimal, Reproducible Example

When asking a question, 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 as creating a minimal, reproducible example. Other names may occur (see footnote).

This is to ensure your code is following these guidelines:

  • 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 question itself.
  • Reproducible – Test the code you're about to provide to make sure it reproduces the problem.

Minimal

The more code there is to go through, the more time it takes users to find your problem and the less likely they are to find it. 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.
  • 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.

However, 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.

Complete

Make sure all information necessary to reproduce the problem is included in the question itself:

  • If the problem requires both code and a file, include both the code and the contents of the file. And if it involves an image also, then include it as well. 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.
  • DO NOT use images of code. Copy the actual text from your code editor, paste it into the question, then format it as code. This helps others more easily read and test your code, and helps with many other problems.

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, 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 question.
  • Eliminate any issues that aren't relevant to the problem. If your question isn’t about an error, ensure that there are no errors.
  • Double-check that your example reproduces the problem! Always test your code before posting to verify it still exhibits the same problem you're asking about.

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. Also, make sure to check the tag for your specific programming language for more information.

3
  • 1
    Suggestions: Change "Other names may occur (see footnote)" to "Other terms may be used (see footnote)" and make sure you include the footnote. Change "If the problem requires both code and a file" to "If the problem requires both code and a data file" because I do not really understand the section "both code and a file". Would it be worth adding a note about the size of the data file? Hinting that it should also be small.
    – AdrianHHH
    Commented Feb 24, 2022 at 18:18
  • @AdrianHHH Yes, I've deliberately not included the footnote, which was obviously a mistake. The footnote is important and should've been included in the discussion, but I didn't. I don't understand your second objection though... A file and a data file is exactly the same in my opinion. Would you like to elaborate? But yes, it probably should be suggested that the file content should be small enough, but this is an area where I think the mere context would sort it out. Maybe, I don't know. Commented Feb 24, 2022 at 18:33
  • 1
    The bare word "file" bothers me. I wonder what sort of file with what sort of purpose. Code is normally placed within a file. Perhaps it should be rephrased as "If the problem requires both code and data, include both the code and the data" or could simplify that to "If the problem requires both code and data, then include both"
    – AdrianHHH
    Commented Feb 24, 2022 at 18:39

You must log in to answer this question.

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