15

On multiple occasions I asked a question, and people asked for example code. Often the nature of the problem called for a relatively complex example, with multiple files, sometimes in different folders. In these cases I have given a GitHub repository as an answer. I understand that I am supposed to create a minimal example, and that a GitHub repository changes over time.

So what is the Right Way(tm) to give such complex examples?

Update: this question is not about how to reduce the example to be minimal. That would worth another discussion. I also would not like to debate whether there are problems which actually need more files/folders to present, that would be yet another discussion. The only question here is that once I have a minimal example on my filesystem which still contains more files and directories, how it is best to present that structure in a question.

Here is an example, presented in a way which requires efforts to be recreated. There should be better way to present than this:

src/categorizerai
src/categorizerai/__init__.py
src/categorizerai/ExampleService.py

Where __init__.py is empty, and ExampleService.py have the following code:

from winterboot.Autowired import Autowired

underlyingService = Autowired('underlyingService')

@Service
ExampleService(object):
    def serviceCall(foo: int = 0) -> int:
        return foo+1;

Update: I am not asking what to provide. I am interested in how to provide. The way I have provided it above does not satisfy me, as it takes effort to recreate. I see nice solutions for some problem domains, like rextester.com for sql. I am looking something like this for domains as generic as "eclipse project".

9
  • 22
    Personally I'd love to see more questions formulated as failing unit tests. That would isolate the problem code and drastically increase the number of times people solved their problems in the process of attempting to write questions. Just refactoring to isolate the problem would identify lots of problems. Commented Jul 22, 2019 at 19:19
  • 12
    Minimal = Take away everything that is not necessary for the problem, whatever remains is the thing. Minimal might be very large, but almost always is not. For example: Are you sure that multiple files in multiple folders were a requirement for the problem you asked about? Commented Jul 22, 2019 at 21:03
  • It's unlikely you really several different files to illustrate your problem. At worst, you probably need a section of code from each file - say, a function or two, or a method and a class or something. So, you don't need to show all the code, if the problem occurs only within the scope of three functions, even if they belong to three different files. It might further turn out that it's not even the entire function, so you can prune some code to expose (or at least narrow down) only the section(s) where the problem occurs.
    – VLAZ
    Commented Jul 22, 2019 at 21:13
  • 1
    Remember, MCVE/MRE is beautiful.
    – E_net4
    Commented Jul 22, 2019 at 21:43
  • So be it. Example: If you need to have 5 pages to demonstrate the bug or error which your question contains. But if you remove 2 pages and the bug still occurs it's not [mcve] at all
    – Shinjo
    Commented Jul 23, 2019 at 7:58
  • 4
    Once you start simplifying the code (e.g. instead of fetching data from the DB with a complex query you just hardcode 2 results that still give the same issue) you'll find that you basically comment out 99% of the code. This also helps a lot in debugging and you'll find that you are able to solve your own problems quite often without posting a question. Commented Jul 23, 2019 at 8:15
  • updated the question to narrow down to the specific problem I have Commented Jul 23, 2019 at 10:37
  • While complex code examples require effort to recreate, guesswork still requires more. So the best way to present is to present it entirely. As long as it's at least close to MCVE ofc.
    – IcedLance
    Commented Jul 24, 2019 at 9:30
  • @ErnodeWeerd "you know what the problem is and you no longer need to post a question" That's not true. The question is of course how to solve the problem. Knowing the problem doesn't imply knowing the solution. Knowing the problem is necessary but not sufficient for debugging. Commented Jul 31, 2019 at 21:32

6 Answers 6

37

Having complex examples is usually the first sign - minimal is not complex.

You should start by breaking your complex example down into something simpler. Pare it down to isolate the actual core issue. If the core issue does involve interleaving with multiple components, try to isolate your code example so that the same aberrant behavior occurs with one of the components you wanted to showcase.

If you can't pare it down, at least try to simplify. Your code can have a few moving parts, but it's ill-advised to ask a question on the whole as opposed to the portion that really matters.

5
  • 3
    Thank you, but the question was not about how to produce a minimal example. It is about once I have the minimal example, how to present it in a question. Commented Jul 23, 2019 at 10:38
  • 1
    @ÁrpádMagosányi I think the way you've done it is okay. Questions are read by humans, not automated scripts.
    – user202729
    Commented Jul 23, 2019 at 15:14
  • Addendum: If the most minimalistic example is complex, even after a couple rounds of breaking it down, you may have inadvertently tripped over either a problem with the implementation or the language standard itself. Or just run into an edge case that's infrequent enough that most people don't even know it exists. Commented Jul 23, 2019 at 23:55
  • I would like to have a way where the humans should only be concerned by the question, and leave recreating the problem to automated scripts. Commented Jul 31, 2019 at 14:56
  • @ÁrpádMagosányi a dumb way to go about it is to remove half the code. Then the half of that half. And so on.
    – Braiam
    Commented Jul 31, 2019 at 17:51
8

Just looking at the example, it has the following problems:

  • It looks like you're depending on some framework, but you haven't named the framework.
  • The Service decorator isn't defined anywhere, neither via import nor directly.
  • There doesn't appear to be any particular reason why you need multiple files. You're only showing one code block.
  • You assigned underlyingService and then never used it. It's thus not clear why you needed to create it.
  • I can't find any real information on this winterboot package. All I can find on it is the package and the repository, neither of which has any examples or documentation about usage. Since this information isn't easily available, you should mention any references you're working with (blog posts, tutorials, API docs, whatever) for context and explain exactly what it is your code is supposed to achieve, including specifying any little fiddly details and edge cases.

It appears to me that you're having trouble putting yourself in the reader's shoes. You need to step back from your code and ask the question, "What might my reader not know? What might they have difficulty making sense of?" and you need to write your post in a way that answers those questions preemptively.


The other thing you need to work on is identifying what is actually required and stripping out anything that isn't completely necessary. Maybe you do need multiple files here, but if you don't understand why you do and don't explain it in the question (at least indirectly, for example maybe the context of the framework you're trying to use makes it clear why multiple files are needed), then maybe it's not actually required. You're going to have to look at each detail and make sure you understand the reason you're including it. If you can't think of a reason it has to be there, then try to find a way to craft your example code without it. Maybe you can just shove everything in one module and be done with it, or maybe when you try to, it doesn't demonstrate what you need it to. Incidentally, that's part of the debugging process: if a change makes the behavior in question go away, then you need to stop and figure out why that is, which is likely to save you from even posting the question at all or may lead to a much narrower question than you originally set out to write. This is all part of the research that goes into asking a good question.

There's no step by step process for creating an MCVE. You have to work it out on a case by case basis and think all the details through. You have to understand what each part of your code does, with the possible exception of the one, narrow little bit that you're asking about. If you don't understand all the other parts, then you need to work on solidifying that understanding before you ask.

6
  • I suppose the winterboot thing is just place holder for the real package name...
    – user202729
    Commented Jul 23, 2019 at 15:26
  • @user202729 No. It's a real package. I linked to its PyPI page and its repo.
    – jpmc26
    Commented Jul 23, 2019 at 15:26
  • As it is just an example on how to show something I did not make much effort to come up with a real MCVE, just something which looks like one. Your observations are valid, just irrelevant to the question I have. That said, for the example to be an MCVE I should have provided a requirements.txt and a script to recreate the actual problem. That is two additional files (or one, if I do pip3 install in the script). Commented Jul 29, 2019 at 7:54
  • If I have no assumption of OS packages present I also had to provide some way to obtain them, which in turn depends on the OS, which leads to another related question that if you take recreatability seriously, you actually have to submit a vm/docker image. Which is obviously not minimal as is, but if there was an agreement that a specific directory should contain the minimal example, and everything else is just clarification of the environment, then it would be a way to produce easily and specifically recreatable, observable and minimal example. Commented Jul 29, 2019 at 7:57
  • @ÁrpádMagosányi "As it is just an example on how to show something I did not make much effort to come up with a real MCVE, just something which looks like one. Your observations are valid, just irrelevant to the question I have." Well, this is kind of indicative of the problem you're having, isn't it? You present an example, but the example doesn't demonstrate the problem you're having. So you get an answer that doesn't solve your problem because it was based on your example. You have to carefully craft your examples to specifically emphasize the problem you're facing.
    – jpmc26
    Commented Jul 30, 2019 at 6:39
  • @ÁrpádMagosányi Yes, you can make some assumptions about the base environment you're working with. Many of those are built into the technology you identify in the question. If you specify the question is about Python, that carries a slew of information that's necessarily true because Python guarantees it. But you could also be using a package with a native component, and then maybe your OS and how you installed that package become important. So you need to be able to identify what things you can't assume your reader will be sure about and then be clear about them.
    – jpmc26
    Commented Jul 30, 2019 at 6:44
7

The requirement is minimal. Not simple, not small. If the minimal example is above average long, then so is it.

If your question is closed, or treated by being closed on the MCVE requirement, you have a good chance of a reopen, if you believably prove that no significantly more simple example can be created.

Although the general downvote/closevote tendency of the site might cause some trouble. Possible, that ultimately you will end up with a closed/downvoted question and with a closed/downvoted/deleted meta post.

3
  • 3
    I'm slightly confused. Simple is not a requirement but proving that no simpler examples can be created is? What is the relation between minimal and simple? Commented Jul 22, 2019 at 21:08
  • 4
    @Trilarion Proving that no simpler exist is not a requirement, but might be required as an argument in the debate about the closure. Minimal is the possible simplest, "simple" is the typical code size of the well-treated MCVE posts.
    – peterh
    Commented Jul 22, 2019 at 21:09
  • "minimal" means "as simple as possible, but no simpler". For some problems, "as simple as possible" might not be especially simple. However, this risks that your question may be judged to Need More Focus. Commented Jan 4, 2023 at 5:00
5

If you can not reduce the code to something short, you are not asking a useful question, and your question is off topic.

Despite appearances, this is not a site for getting strangers to debug your code for you. It is not a help site for your code. Questions and answers here are meant to have lasting value: a good question and answer here should also be potentially useful to someone else. Someone else with a problem must be able to search for problem like theirs, and learn from the answer(s) to the question(s) they find. That means that questions must be free of extraneous details. Specific debugging questions are useless to other people, because nobody will have code exactly like yours.

We often ask for an MCVE, which suggests we want a complete example. But this is a trick. You see, if you start with a large body of problematic code and attempt to reduce it to a minimal example, you are engaging in the process of debugging yourself, and that is actually what we want you to do. We are not here to do that debugging for you. Carried to completion, that process has only three possible outcomes:

  • You have discovered the cause of the problem. And therefore no longer have a question to ask.
  • You have reduced the problem to some behaviour of the programming language, and that behaviour is difficult to understand, counterintuitive, or surprising. And you therefore now have a useful question about that behaviour of the programming language, which would be useful to anyone else using that aspect of the same language.
  • You have reduced the problem to some behaviour or documentation of an API or library you are using, and that behaviour is difficult to understand, counterintuitive, or surprising. And you therefore now have a useful question about that API or library, which would be useful to anyone else using that API or library.

So, don't provide a complex example. If your question is really how do you debug complex code, then I'm afraid you are asking a question that can not be answered in the format of this site, because that is one of the complex multifaceted skills that professional and enthusiastic programmers never stop learning and improving. A good starting point is to learn how to

  • interpret error and warning messages from your compiler
  • interpret log messages from the libraries, frameworks and operating system you are using
  • interpret messages and stacktraces from the runtime environment
  • use a debugger
  • unit test code to rule out particular failure modes
1
  • 1
    "But this is a trick. You see, if you start with a large body of problematic code and attempt to reduce it to a minimal example, you are engaging in the process of debugging yourself, and that is actually what we want you to do. We are not here to do that debugging for you." Brilliantly put, and something I have tried to explain many times. Commented Jan 4, 2023 at 5:06
1

Self-answering, based on things learned on the comments and other answers, as none of the answers seem to address the specific question I have (my original wording was not precise enough).

So far it seems to me that the best way would be just stick to the form presented at the answer, and probably adding a reference to a git tag which contains the same, and maybe some setup script to articulate environmental assumptions which are otherwise hidden. (I usually work with docker containers containing all the dependencies and development tools needed, and a Makefile where the "testenv" target "wraps" the container around the current working directory, so it is easy for me.)

This way I would

  • present the relevant (and minimal, working) example right in the question, while
  • make easy to recreate the problem, and
  • no assumptions are hidden, and
  • I can work in reducing the example in my comfortable environment, and
  • by providing a tag it is unchanged over time despite being in a git repo.

Any comment/up- or downvote on whether it is a good idea, or how to improve it are welcome.

1
  • 1
    It might be helpful if you can provide a requirements.txt and/or a Dockerfile that can be used to re-create your env. Commented Aug 1, 2019 at 1:13
0

In cases where I've had a complex implementation but the only thing which applies to my question is a portion of my code, I have pulled out the relevant sections with additional comments to provide context into an individual Gist on Github.

For example, I may include contextual classes and other functions and then include the main issue around which the question revolves.

You must log in to answer this question.

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