Checklist for how to write a good Code Review question

Question

Many questions of new users lack some parts or common style of the site. There already are some meta questions that aggregate tips on this issue but letting new users walk through all of them is probably very discouraging.

Instead I would propose to make a community wiki question and answer with a short checklist for posting questions on CR.

It must be short enough to not scare people from reading it through and it should provide links to more detailed meta questions that explain why.

An example could be

1. Check that your code works -> link to help center for on topic questions
2. Check that your code works -> link to meta post with some rough guidelines where to post non working code
3. Choose title -> link to meta post with some good question titles
4. Copy&paste your working code -> link to meta post on "Which parts of code may be ommitted"
5. Add some context about the overall algorithm and the usage in your program
6. [Optional] State major concerns or objectives for the review
7. Add at least the tag of the language you are using
8. Post and enjoy

So what do you say? Should we put up such a list? What should it look like/what should the items be?

Should we even go one step up and make a flowchart on how to use the SE network during programming to get people to better understand when to post on CR?

Answer 1

Perhaps something like this could help situate CR in StackLand:

Answer 2

How to NOT write a zombie.

A zombie is a question that remains unanswered. As a question asker, your goal is to avoid writing one.

Beyond meeting the on-topic requirements, I think "good CR questions" can be broken down into several question types.

This answer is longer than I would have liked, but there are pictures.

---

The Minimalist

These questions show the bare reviewable minimum - enough to be deemed on-topic by the community of course (although there have been one-liners deemed "reviewable"); these questions typically contain a small code snippet, but not an entire procedure or function - there's something specifically in that snippet that doesn't look right, you have doubts about the way that thing works, you post it on CR.

These questions typically ask about whether the algorithm could be refined, or how performance could be improved: they're much more about optimization than naming, but readability still a valid concern.

These questions can often be answered quite quickly. The flipside is that the less substantial "minimalist" questions may sometimes attract StackOverflow-ish answers that are frowned upon, because they're either code dumps without explanation, or "quickie" answers that don't really review the code. When that happens, it's possible that the question gets protected if the question is very active.

"Minimalist" questions that are off-topic, usually get closed very, very quickly, too.

Sub-types

• The Tune-Up, where OP is specifically concerned about performance. These are often programming-challenge entries that don't run fast enough. Keep in mind that answers may address any aspect of your code, even things completely unrelated to performance.
• The A vs B Comparative, where OP is showing two snippets, and asks whether snippet A would be better than snippet B (or vice-versa). Don't be surprised if an answer describes solution C as a better alternative, while showing both snippets' weaknesses.

Zombie rating:

---

The Proverbial Review

These questions are a majority. They include a method (including its signature) and, ideally, some calling code and enough context to describe what's going on. Or it could be a whole class, perhaps even two or three with an interface, a few members and a funny smell.

These questions simply ask for peer review, they're the proverbial does this code make my ass look fat? "ideal" question, where reviewers comment on everything there is to say about your code.

Reviewers love those. Fanatic reviewers eat two or three for breakfast, and another before lunch.

Sub-types

• The Follow-Up, which happens after a first question's code was reviewed, and the recommended changes from one or more answers have been implemented. The updated/refactored code is posted for yet another review, linking to the original question for context.

Zombie rating:

---

The Project Review Project

An entire small project can be posted for review, given that it fits the 60K maximum characters in a Stack Exchange post. Writing a good question like this requires mastery of markdown formatting to keep readers hooked and able to follow along.

If your code is a complete mess, it's probably better to only post a part of it. Use the "review project" question type for when you have literally crafted something to the best of your abilities, and would like a peer review to either confirm your thoughts or shred that code to pieces.

The name says it. Reviewing that code is literally a project in itself, and that takes time. If you're expecting a quickie answer, you've asked the wrong type of question.

The title is always very important, but even more so with these questions - make sure you have a title what will draw attention. Be witty.

Zombie rating:

---

Zombie Penalties

If your question is on-topic, it probably falls in one of the above categories. So you have a number of "zombies" in your rating; now consider these [cumulative] penalties:

Your language tag isn't in the top 40 tags: add 1 zombie.

Your code heavily depends on obscure 3rd-party libraries or frameworks: add 2 zombies.

Your code can fly a rocket or perform heart surgery: add 3 zombies.

Now add all applicable ratings; the more zombies, the longer the time-to-answer¹.

---

_{¹Very, very rough rule of thumb.}

Answer 3

Simon's Guide for posting a good question

There are a lot of questions that appear on Code Review, and all questions are fighting for reviewer attention. This is a non-exhaustive list of items that I am looking for in a Code Review question when determining whether or not I should review it and how I should vote on it.

If your question is lacking a lot of the following, then it is very likely that I will down-vote it.

Is your question on-topic?

Make it clear whether or not the code works and produces the correct results.

Have you stripped your code from context before posting it on Code Review (not good!)? Is the code you are posting on Code Review your real code and exactly your real code (good!)?

Motivation

Why did you spend time writing this code? Why does this code exist?

You might also want to say why you decided to post a question on Code Review. What are you hoping to improve in the code? If you have no specific wishes for improvements, just say something like "Any and all improvements welcome".

Usage code, example inputs and outputs

How to use your code? Is it a game that anyone can just copy and compile and run? Is it some library, or some methods, that should be used from other code?

If your code is some algorithm with a clear set of inputs and outputs, provide at least a few sets of input and output pairs. This will help reviewers understand what your code does, and to see what edge-cases you have already thought of.

If your code is for printing things to the console, provide an example output of what your program prints.

Description

Don't just say "This is my code, can I make it better?". A reviewer does not want to read your code to understand what it does, the reviewer wants you to give a bit of explanation about what your code does and then the reviewer will decide if it is worth reviewing or not.

When asked to give more description about what your code does, don't just say "Can't you read the code?". You are the one who wants your code reviewed, then it is up to you to make your question interesting.

Describe the details and your approach

How did you approach the task of writing the code? How did you disassemble your problem? How did you assemble your solution? How do you eat an elephant?

There are many different ways to write tic-tac-toe or sudoku. How flexible is your approach? Do you support different sizes or other parameters? Have you used nine variables, a one-dimensional array, or a two-dimensional array?

To implement a certain algorithm, are you using a hashmap, a list, a set, a stack, or a queue...?

Class/Method summary

If you include multiple classes in your question, add a short summary about what each class is responsible for.

If you include only one or a few classes in your question, make a little list before you present your code about what functions/methods exists.

Don't assume that everyone knows what you are talking about

If you are making anything that few people know about, make people learn things just by reading your question.

If you are making a tool for something that few people know about (such as an already existing game or application), describe the context and maybe even describe why you wanted to make this tool for that game/application.

Even if your code is about something that is very common knowledge, such as playing tic-tac-toe, you can still include a link to the Wikipedia page.

Does your code do anything useful or interesting?

At least to me, reading code about interesting things (or in interesting ways) is much more interesting than reading yet another ordinary fizzbuzz.

Screenshots

If your code has some sort of GUI, add one or more screenshots of how it looks.

Take your time, don't be lazy

Never say "I want to do XYZ as well but I am lazy and haven't done so yet" or "I know that I should clean up the XYZ class/method but I have been lazy".

And absolutely do not say "I want to do this using XYZ instead, can you please write the code for me?"

Don't just write the code and put it up on Code Review as fast as you can. Review it yourself before asking us to review it.

Possible things you cannot use

Are there any restrictions that prevent you from using some techniques that you are familiar with, but prevented from using? (A common one is: What version of Java are you able to use? Can you use Java 8?)

Especially if there are restrictions that may seem arbitrary, provide reasons for why the restrictions exists.

Answer 4

Something like this could work:

1. Your question must contain your own real, working code.
2. Your question should provide an explanation of the code.
3. Your question may include a list of specific concerns.

This should be obvious to anyone who has read and understood the material in the relevant parts of the help center, though.

Creating a "reader's digest" version of /help/on-topic and /help/how-to-ask can't hurt, but the real challenge would be getting this information in front of the people pushing for migration.

Answer 5

The number one most important thing you can do is:

Explain what your code is supposed to do!

All too often, questions on Code Review look like this, and are simply impossible to answer.

This is a program I've written. Is it any good? Should I have used a class? Do you have any tips for how to make it faster?

def process(tbl):
    it, res = [], []
    for item in sorted(tbl.keys()):
        it.append((item, tbl[item]))
    for i in range(len(it)):
        if it[i] == it[0]:
            continue
        it1, it2 = it[:i], it[i:]
        if sum(it1) < sum(it2):
            res.append((it1[-1][0] + it2[0][0]) / 2)
        else:
            res.append((it2[-1][0] + it1[0][0]) / 2)
    return res

Try to put yourself into the position of a reviewer. We don't know what problem you were trying to solve, unless you tell us. We don't know how this code was supposed to solve the problem, unless you explain it to us. And if we don't know what code is supposed to do, we can't review it.