# Checklist for how to write a good Code Review 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"
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?

• I really wish we could force users to need at least one language tag. It's frustrating to see questions and not know what language it is. – RubberDuck Jun 14 '14 at 21:25
• Related: What makes a good question? – 200_success Jun 16 '14 at 8:24
• – Simon Forsberg Jan 6 '16 at 13:26

Perhaps something like this could help situate CR in StackLand:

• As mentioned in the chat I would have liked a branching version but this is probably better (because it is simpler, see the rule of three comment on Dagg's answer :). – Nobody moving away from SE Jun 14 '14 at 21:29
• You should post this to regulars on the three other sites you mention there and see if they agree with the way you describe them. – Simon Forsberg Jun 14 '14 at 21:39
• @SimonAndréForsberg the same way CR isn't limited to maintainability, I'm sure there's much more to UX than the icons in the UI, and more to Programmers.SE than high-level architecture. Was just to give an idea, not to fully 'describe' each site. It does make it clear where CR stands in the process though. – Mathieu Guindon Jun 14 '14 at 22:55

# 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 could be refined, or how could be improved: they're much more about than , but still a valid concern.

These questions can often be answered quite quickly. The flipside is that the less substancial "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 entries that don't run fast enough. Keep in mind that answers may address any aspect of your code, even things completely unrelated to .
• 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-answer1.

1Very, very rough rule of thumb.

• Something that was glossed over here (for good reason) is that a good question includes the method signature. It's sometimes hard to give a proper review without one. – RubberDuck Aug 19 '14 at 11:48
• How many zombie penalties are applied to a question about an algorithm for detecting zombie processes? – David Harkness Sep 7 '14 at 7:29
• Original zombie artwork under CC-by-SA per ztreasureisle.wikia's terms: ztreasureisle.wikia.com/wiki/File:Zombie-icon.png – Mathieu Guindon Aug 10 '16 at 19:20
• So the maximal zombie question is a Haskell project that flies a rocket by accessing an API through the Tor network? – Anakhand Jun 26 '20 at 15:06

### 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.

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 or . 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.

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 .

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.

• Can't stress the example inputs and outputs enough. The examples should include edge conditions if possible (e.g. empty list passed in to a sort/search function). – itsbruce Jan 6 '16 at 13:39
• @itsbruce Indeed. Just moved the usage + example input/output a lot higher up and added a note about edge-cases there. – Simon Forsberg Jan 6 '16 at 13:42
• I remember coming up with something like this quite a while ago, but this is much better. +1 :) – Ethan Bierlein Jan 6 '16 at 15:42
• Also see this answer by 200_success for information to add in the question. – Simon Forsberg Jul 22 '17 at 19:50
• (eating elphants on web archive.) – greybeard Nov 13 '18 at 12:05
• @greybeard Sad to see the original gone, thanks for finding it on the web archive – Simon Forsberg Nov 13 '18 at 19:32

Something like this could work:

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.

• The check-list is a good one and I endorse this comment but for an odd reason: the Rule of Three. The Rule of Three is that any list should contain three and only three items. If detail is necessary, each item should have three sub-items (or none but not just one or two). Three is more than just arbitrary; much research has shown that, while many can handle more and a few are limited to less, almost everybody can mentally manipulate groups of three. – We B Martians Jun 14 '14 at 14:52
• A minor addition on 3: You will not try to force CR to only review those properties of the code you're interested in. The moment you post your code, it's fair game for long reviews and nitpicks. Don't dare trying to convince us otherwise. – Mast Mod May 30 '15 at 9:51

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.