Early 2018 we changed the close reasons on Code Review. This was necessary, but now almost 2 years later it's perfectly clear there's a growing discontent with one of them: "Lacks concrete context".
In this post, I'll provide a bit of ehm, context about:
- History on the problem
- Signs there is a problem
- The core of the problem
- Reasons we can't simply throw the problem overboard
It's going to be a long post with a lot of links, but we've been dancing around this problem long enough now so I want to be thorough.
Feel free to post alternate solutions and/or alternate phrasings of the close reason in the answers. The goal of this question is to come up with a fix that:
- helps moderating users (anyone voting and in the queues) by picking the correct course of action based on our scope
- helps new and existing users with fixing their question should it get closed
- reduces the growing resistance to our close reasons
All explicitly by improving (the usage of) this particular close reason. One way or another.
This all started in January '18. Peilonrayz correctly remarked the old reasons weren't working out. We went from this list:
- Questions containing broken code or asking for advice about code not yet written are off-topic, as the code is not ready for review. After the question has been edited to contain working code, we will consider reopening it.
- Questions must involve real code that you own or maintain. Pseudocode, hypothetical code, or stub code should be replaced by a concrete implementation. Questions seeking an explanation of someone else's code are also of-topic.
- Questions must include the code to be reviewed. Links to code hosted on third-party sites are permissible, but the most relevant excerpts must be embedded in the question itself.
- Authorship of code: Since Code Review is a community where programmers improve their skills through peer review, we require that the code be posted by an author or maintainer of the code, that the code be embedded directly, and that the poster know why the code is written the way it is.
- Lacks concrete context: Code Review requires concrete code from a project, with sufficient context for reviewers to understand how that code is used. Pseudocode, stub code, hypothetical code, obfuscated code, and generic best practices are outside the scope of this site.
- Code not implemented or not working as intended: Code Review is a community where programmers peer-review your working code to address issues such as security, maintainability, performance, and scalability. We require that the code be working correctly, to the best of the author's knowledge, before proceeding with a review.
For those with 10k+ rep, find the full history here.
200_success explained how and why, and it worked fairly well. Except this point didn't work out:
- Instead of just banning "pseudocode, hypothetical code, and stub code", we focus on explaining what reviewers are looking for: sufficient context.
Problem? I thought we just fixed it?
It was more than a good step in the right direction, absolutely. But, while the idea behind the close reason would appear to be clear, it's a common source of confusion . And there have been attempts at fixing it, but we're almost 2 years in now and so far no joy. I've picked the wrong reason myself often enough, and sometimes so many reasons apply it arguably doesn't matter much at all (such questions are usually unsalvageable).
But it's too much up for opinions at the moment and we need something clearer. Not just for us, but for the next round of people arriving, sticking around and taking up moderating responsibilities.
Please post suggestions which are clearer than the current reason.
So people don't like the close reason, what's the problem with it?
Core of the problem is that the close reason is both misunderstood and misapplied. The latter is in part a logical consequence of the former.
Where LCC was supposed to be used when the code was missing code-context (or at least enough description as substitute, if need be), it's used for a lot of things.
Can we discard it?
Absolutely not. Often enough when an attempt is made to review a question with code that leaves us guessing at the intentions of the poster, it turns out the answer is useless. It's a problem we share with hypothetical code.
Or, as Dan put it years ago:
Put it this way: Imagine you post a section of code and we give you a review and a potential change to the code.
Someone spends an hour basing his reply on this change.
You then say "I can't do that, because the foo can't be barred. That bits not in my question, but its part of the same part of code"
You've now wasted another person's hour because you didn't include the entire context in your original post.
I appreciate that may or may not be the case in your example, but its (one of) the reasons we dont' accept example or partial code here.
Emphasis mine. (source)
Not having enough context means we can't review it or a review would be a waste of everyone's (including whoever asked the question) time. Effectively questions like that hold no value (yet). They can often enough be fixed, but to fix a question we need to enlighten the poster what's wrong with the question. Part of that is leaving comments (which we don't do enough), but it starts with using the right reason to close a question.
We can't accept the current unclear situation as the new normal.
- use the proper reason
We need to clarify the close reason so it isn't abused as easily, and finally, we need to stop abusing it. It's basically that simple.
Is a question:
- overall unclear?
- missing a specification (what is the code supposed to accomplish)?
- missing a description?
Unclear what you're asking.
- missing complete portions of a function?
- missing functions or libraries that have to be included for a meaningful review?
Lacks concrete context.
- missing all code, is all code behind a link or are essential parts behind a link?
- asking about why code works the way it does?
Authorship of code.
Keep in mind, there's the 'Other' reason to vote to close if we can't (or shouldn't) help the poster for a less clear-cut reason. If you think this clarifies things, use it. It may ruin the closure stats a bit, but I'd prefer a clean, efficient site over clean stats.
Also keep in mind that code doesn't have to be posted completely per our current scope. If the posted bits are enough to review it, review it. Do you prefer more-than-average context? Fine, so do I. Pick a different question to answer. We got plenty.
missing a specification? I'm not clear on what that means. \$\endgroup\$
asking about why code works the way it does?\$\endgroup\$