Questions should include a description of what the code does

Question

Related:

• What criteria do you use to upvote a question?
• What makes a good question?

I feel that it is currently too easy to copy some code that you have written and put it up for review here on Code Review. My opinion is that if you want a review of your code, then you should also be able to provide an explanation about the code.

Horrible examples of question with far from sufficient descriptions:

• Dangerworld game
• Implementing an encryption standard over message text
• D3.js zoomable map

(Yes, three of these also have horrible titles, but that's an entirely different subject)

OK examples of questions with some description provided, but it could include some more details/overview/comments of the code: (Depending on how you look at them, you could argue for both sufficient and not sufficient description)

• Android GameWatch game for learning/review
• Determining common divisors of two numbers
• Integer Partition

Good examples of where sufficient details are given to understand what the code is doing:

• Performance/Optimization of Knapsack(ish) algorithm for move generation for a game
• Another Rock Paper Scissors Lizard Spock implementation
• WIP platformer game
• Poker Hand Evaluator, take 2

Answer 1

I'd like to generalize the complaint: code to be reviewed should include sufficient context.

In particular, I've noticed that many sql questions are frequently bad at providing sufficient context for a code review. I've added the following admonition to its tag wiki:

If you request a code review for an SQL query,

• Provide some context about what your query is trying to accomplish.
  • Does it as an offline batch job on a reporting database? Or does it run on your primary database, and the user expects an immediate response?
  • Does the code execute the query in one shot, or does it execute the query many times in a loop?
  • Are there any tables where the number of rows could be a concern?
• Include sufficient information about your database schema (table definitions)
• If query performance is a concern,
  • Ensure that indexes are in place, and mention them when describing the schema.
  • Include the output of EXPLAIN SELECT.

… and called attention to it in the tag wiki excerpt:

Read the tag wiki's guidelines for requesting SQL reviews: 1) Provide context, 2) Include the schema, 3) If asking about performance, include indexes and the output of EXPLAIN SELECT.

If you see SQL questions that lack sufficient context information for a review, please add a comment referring the poster to the tag wiki. In addition, it may be appropriate to vote to close as "Unclear what you are asking" or downvote the question for low quality.

Answer 2

If you can't figure out what the OP is asking after reading the question and asking in the comments, then you should vote to close based on being unclear as to what the OP is asking.

It sounds like there is another post somewhere that elaborates on this.

Answer 3

New close reason proposals was already addressed by @codesparkle:

This [close reason] limit applies to all sites with specific exceptions (not sure if there are any except for Stack Overflow) as explained in this MSO answer. I'm not convinced that there's an urgent enough need for this to warrant asking for an exception though. The wording of the proposed new close reason also leaves a lot to be desired.

Basically, we can only have three close reasons at the moment. The ones we have (non-working code, code behind a link, and code not yet written) are just fine. I do agree entirely with @James about this being what comments are for. If comments don't help reveal more info from the OP, then the question can be closed with one of the existing close reasons, namely unclear what you're asking.

Answer 4

Proposal: This deserves a close reason.

(This is just a first attempt at formulating one, suggestions for formulating are welcome)

To help the reviewers understand your code, questions should contain a description about your code in addition to the code itself. The longer the code, the more description should be provided.