120

I'm seeing more and more questions where the asker posts an excerpt of code, that by itself is not runnable, with a link to a GitHub repo and... that's it. (In some of the more egregious examples, there isn't even an excerpt.)

Unsurprisingly, most of these questions are terrible trash that quickly get closed, which is good - but it would be far better if they were never asked at all. To that end, adding guidance along these lines to the How to create a Minimal, Complete, and Verifiable example help page would assist in this*.

Something along the lines of:

Linking to a GitHub repository containing code with the issue you're posting about is generally not an acceptable substitute for an MCVE for the following reasons:

  • Cloning your code and all its dependencies is a significant investment of time and effort, which is likely to deter people from answering your question
  • Should the repository be deleted, or if GitHub is down, the context of the question will be unavailable, which makes it useless to others
  • (other points smarter people than me will come up with)

Additionally - and here's the big ask - if we could get the "Ask a Question" form to pop up a validation tooltip linking to "How to create an MCVE" when it detects a GitHub repo link in the body of a question, that would be great.

* In an ideal world where people actually read that page before asking terrible questions, of course.

14
  • 40
    I don't think it should mention GitHub/cloning/repos specifically, but it should make it clearer that it's describing a [mcve] in the question itself, with any off-site code (whether that's GitHub, an online repl or sandbox, google drive or anything else) being provided only for supplementary purposes.
    – jonrsharpe
    Commented Feb 14, 2019 at 7:58
  • 100
    I wasn't so sure about this request (as you said, we do not live in such an ideal world, where unicorns roam gumdrop-lined streets and people read documentation), but then I took another look at the Help Center page and noticed that nowhere on that page does it say that the code needs to be included in the question itself. The close reason does, but the Help Center page doesn't. That needs to be fixed, regardless of whether or not we call out GitHub and other specific off-site resources.
    – Cody Gray Mod
    Commented Feb 14, 2019 at 8:05
  • 5
  • 4
    Addendum: Can the question wizard have some text to that effect, and/or quality standards detect a repo link without code, as well?
    – fbueckert
    Commented Feb 14, 2019 at 14:19
  • I must admit I've never seen anyone post a link to a github repo that was intended as an mcve, but I do agree with the general remark about external resources, especially the way @CodyGray worded it.
    – GolezTrol
    Commented Feb 14, 2019 at 14:29
  • I agree with the main thrust of this post, but just want to put out there that a link to a GitHub project is generally not an acceptable MCVE; sometimes it may be appropriate. For example, sometimes in the R programming context, the issue may be needing the correct combination of code fixes and package structure fixes ("You need to add line y to file x, and move file x from R/ to src/" or something like that). While technically possible to include all code and package structure description in the question, it seems silly when you could link to a GitHub repo.
    – duckmayr
    Commented Feb 14, 2019 at 14:30
  • The suggested guidance above looks good, but anything more strongly worded could be taken as a prohibition that I think would be sometimes unwarranted.
    – duckmayr
    Commented Feb 14, 2019 at 14:31
  • 60
    Can we also add that images of code are not acceptable? Commented Feb 14, 2019 at 14:33
  • 10
    @duckmayr Nobody is asking for a blanket prohibition against links to repos. Links are okay. The problem is when people think a link, by itself, satisfies the MCVE requirement. The body of the question should contain enough information so that people looking for solutions to their own problem can readily figure out whether the question is related to the problem they've been having. If the OP is unable to circumscribe what is significant about their code, then that's a good indicator that their question is not suitable for this site.
    – Louis
    Commented Feb 14, 2019 at 15:09
  • @Louis Thanks, good to know. I was inspired to make my comment by a now deleted comment on this question, where OP had included some code and a clear explanation of the problem along with a link to the repo, and someone commented that links to outside resources made it not an MCVE, to which I strongly disagreed. So I know there are some zealots out there on this, but note I also explicitly agreed with how OP stated their problem and suggested guidance.
    – duckmayr
    Commented Feb 14, 2019 at 15:20
  • 2
    JSFiddle links without code are blocked; why not do the same for GitHub?
    – gparyani
    Commented Feb 14, 2019 at 17:49
  • 1
    Nice idea as I also noted an increase of those link-to-github questions (will probably be implemented in 6 or 8 weeks anyway) ! note that if GitHub is down, there will be greater problems in the world :) Commented Feb 14, 2019 at 21:07
  • 4
    @EJoshuaS We could instead emphasize what they should do: "Include the text of the code directly in the question, with proper formatting. Images and links to other resources are not acceptable."
    – jpmc26
    Commented Feb 14, 2019 at 21:39
  • 2
    Definitely, no more images of code that are so easily copied and pasted, links to code especially tons of it that's also easily narrowed down and c/p'd, and long copy/pastes of irrelevant code with one small bit that's actually relevant
    – Jab
    Commented Feb 15, 2019 at 10:31

2 Answers 2

16

It occurs to me that this is really part of providing a complete test case. That section currently reads:

Complete

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

  • Some people might be prepared to load the parts up, and actually try them to test the answer they're about to post.
  • The problem might not be in the part you suspect it is, but another part entirely.

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

I've tried to rework that a bit, borrowing from T.J.'s answer:

Complete

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

  • If the problem requires some server-side code as well as an XML-based configuration file, include them both. If a web page problem requires HTML, some JavaScript and a stylesheet, include all three. The problem might not be in the code that you think it is in.

  • Use separate code blocks for each file or snippet you include. Provide a detailed description for the purpose of each block.

  • Use Stack Snippets to demonstrate runnable HTML, JavaScript or CSS.

  • DO NOT use images of code. Very few people are willing to type out the code in an image to test it, and those that try may introduce errors.

Make sure it's complete

Copy the code from your question into a new file or project, then run it. If it doesn't run for you, then it won't run for anyone else.

My goal here is to avoid adding too much additional text to an article that we're already struggling to get folks to read. Thoughts?


This is now live, with a few additional tweaks from Cody.

15
  • The final section "Make sure..." in particular seems like an excellent addition.
    – jscs
    Commented Feb 15, 2019 at 23:16
  • Most often I see links to other repos when people do share their code but link to some dataset offsite. Far too often they are totally surprised when being pointed to the fact that their code is no mcve, because by their logic the code is minimal and they have made the problem reproducible by linking to the 200 MB dataset. So if this problem can be incoorporated in a rewording, that would be really great. Commented Feb 15, 2019 at 23:39
  • I think putting the last point on a bullet list explaining what MCVE stands for at the start, would get folks more willingly to read it.
    – Braiam
    Commented Feb 15, 2019 at 23:39
  • 1
    Consider bolding the phrase "in the question itself", and omitting the rationale for not using images. There are myriad, and it's not the place to discuss why. Instead, say: "Copy and paste from your editor into the question" (or similar; the point is to guide on what to do).
    – Cody Gray Mod
    Commented Feb 16, 2019 at 4:23
  • 1
    For me, the placement I suggested in my answer was important: Right near the top, above "Minimal." The further down the page you go, the less they'll read. I think where it is now will get a lot less notice than it would higher up. Commented Feb 17, 2019 at 12:45
  • Broaden the last "DO NOT" point to include other kinds of content as well, not just code. You often see ncessary data (a SQL table's contents, a CSV file) in images, too.
    – jpmc26
    Commented Feb 18, 2019 at 5:43
  • I suspect most folks given a link to this page don't read it at all, @T.J.Crowder. There are already "just in time" warnings / blocks for too much code, too little code, unformatted code, images, and off-site code hosting links - clearly those are frequently ignored as well. The best we can do here is help the minority of careful, conscientious users who will read, and to that end I think it's worth making it as easy as possible for them to read the whole thing.
    – Shog9
    Commented Feb 18, 2019 at 22:24
  • The entire article is... kinda specific to code, @jpmc26. There's a somewhat more generic warning shown to new users who actually try to upload an image though.
    – Shog9
    Commented Feb 18, 2019 at 22:26
  • @Shog9 The "generic" message still specifically says "code or error messages." I gave you specific examples of other kinds of content that are commonly uploaded as images. What more do you want? The MCVE page already branches out into other kinds of files; "XML configuration" is mentioned right here in your post. In what way is it impractical to address data being posted as images in these locations? All I'm asking for is like 2 or 3 more items in a list; maybe 10 additional words tops. You could also encourage them to include data directly in the code, rather than have it separate.
    – jpmc26
    Commented Feb 18, 2019 at 23:42
  • @Shog9 - With respect, that's the classic "false dilemma" fallacy. Because many won't doesn't mean we don't try anyway, including putting the important content near the top for those who only read part way. Commented Feb 19, 2019 at 9:23
  • Not sure what dilemma I'm setting up here, @T.J.Crowder? I'm certainly not arguing against including this information. My goal with this page was to create a Stack Overflow-specific guide for debugging questions: the critical problem was so-called "code dumps", folks posting their entire program with a vague description. If there's any unimportant content in the article at all, we should just get rid of it, not shove it to the bottom. FWIW: 30% more people view "How to Ask" than MCVE - I've edited that too.
    – Shog9
    Commented Feb 19, 2019 at 16:14
  • Perhaps instead of trying to create an exhaustive list of everything that shouldn't be an image, we could come up with a short description of the things that images are useful for, @jpmc26?
    – Shog9
    Commented Feb 19, 2019 at 16:15
  • @Shog9 - It was the argument that "I suspect most folks given a link to this page don't read it at all." It isn't an argument not to make sure these bullet points are near the top. Commented Feb 19, 2019 at 16:17
  • "The further down the page you go, the less they'll read" - you're arguing people who do read the page won't read the whole thing, @T.J.Crowder; that's what I was responding to. I'm not disagreeing with you; anything we can do to make the page shorter while preserving content and clarity is worth doing - that's why I went out of my way to rewrite an existing section instead of adding a new one. Keep in mind though, this problem - external / inaccessible code - is not the primary problem that this article seeks to address; at best it is one facet of a much, much bigger problem.
    – Shog9
    Commented Feb 19, 2019 at 16:43
  • @Shog9 I think a list of things that should be in images is equally difficult to list exhaustively, even though I agree a partial list would be helpful. Even if one were added, I still think we'd benefit from somehow discouraging people from screenshotting their data and encouraging including it in text form. As I mentioned, this is something I see happening in the wild. Not every other question, but often enough that it left an impression on me. And it makes reproducing a problem more difficult for the same reasons that code in images does.
    – jpmc26
    Commented Feb 20, 2019 at 1:11
45

Big yes on updating the page to say not to do it.

Suggest shorter, direct sentences with bullet points and boldface. For instance, just before the Minimal:

Do

  • Do include your MCVE in the question text, as text in a code block or runnable Stack Snippet.

Don't

  • Don't link to your code offsite unless you also include all necessary code in the question text as well.
  • Don't post images of code. Always include code as text in a code block or Stack Snippet.
  • Don't say there's too much code to post. That's why you need to reduce it to an MCVE.
  • Don't use a Stack Snippet for something that doesn't run and demonstrate the problem when you click Run in the Stack Snippets editor.

(Not linking offsite includes not linking to GitHub, jsFiddle, CodePen, CodeSandbox, Plunker, or similar without also including the code in the question itself. It should be possible to answer the question without following the link at all.)

More explanation could be included, but clear, standout bullets may (may) actually catch someone's eye.

("Stack Snippet" above should be a link to the Stack Snippets help page that still somehow doesn't exist. That page should be official help, not just the Q&A version.)

3
  • 3
    Totally agree with this. Too often, I see these exact issues. On a side note, it might be interesting to consider the system to automatically run the snippet to see if any errors are thrown. If any errors are thrown a message box should appear notifying that "It would appear your stack snippet throws an error, does this demonstrate your issue" (something like that).
    – kockburn
    Commented Feb 15, 2019 at 12:59
  • 1
    It should likely include something about the fact that Stack Snippets are only for HTML/CSS/JS code, not for PHP, C#, etc. I know your post helpfully says that, but you know people and reading... Commented Feb 15, 2019 at 18:00
  • 1
    I'd broaden this to include other kinds of content as well, not just code. You often see data (a SQL table's contents, a CSV file) in images, too.
    – jpmc26
    Commented Feb 18, 2019 at 5:43

You must log in to answer this question.

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