Let's draft better Help Center pages!

Question

To follow up on Help spot deficiencies in our Help Center, let's collaboratively draft better Help Center pages.

For each Help Center page to be modified, post a Community Wiki "answer" containing the original text of the page. Please try to reproduce the markup as faithfully as you can. Then, everyone can start editing it! (Be sure not to edit your own post within the first five minutes, else your modifications will be incorporated into Rev 1.)

Answer 1

The Help Center page and its Deficiencies and then some more

---

What should I do when someone answers my question?

The first thing you should do after reading someone's answer to your question is vote on the answer, like any user with sufficient reputation does. Vote up answers that are helpful, and vote down answers that give poor advice. Other users will also vote on answers to your question.

As the author of the question, you have an additional option: accepting the answer that gives you the most helpful advice. To mark an answer as accepted, click on the check mark beside the answer to toggle it from greyed out to filled in. You may change which answer is accepted, or simply un-accept the accepted answer, at any time.

Accepting an answer is not mandatory; do not feel compelled to accept the first answer you receive. Wait until you receive an answer that answers your question well.

What should I not do?

Do not change the code in the question after receiving an answer. Incorporating advice from an answer into the question violates the question-and-answer nature of this site, and removes the context necessary to understand the answer or answers.

Do not add an improved version of the code after receiving an answer. Including revised versions of the code makes the question confusing, especially if someone later reviews the newer code.

Please refrain from posting a comment that merely says "thank you." Voting and accepting are the preferred ways of saying "thank you" on this site, as they confer reputation points. Comments are meant for requesting clarification, leaving constructive criticism, or adding relevant but minor additional information — not for socializing.

I improved my code based on the reviews. What next?

First of all, consider accepting one of the answers. If one of the answers gives you good advice with clear directions for improving your code, just accept the best answer and upvote any other answers you feel were helpful. We don't necessarily have to see exactly how you applied the advice to your code.

If you'd like to share the revised version of your code, the following are acceptable (and by no means mandatory) options:

1. Posting a new question. If you incorporate advice from one or more answers, but are still unsure that the code is as good as it should be, then post a new question with your revised code. For the benefit of other users, add mutual links: mention the previous question in the new question, and add a comment on the old question linking to the follow-up question.

2. Posting a self-answer. If you want to show everyone how you improved your code, but don't want to ask another question, then post an answer to your own question. Self-answers are acceptable on Stack Exchange sites, and even encouraged: there is a self-learner badge you can earn for that. Please note:

   • Your answer must meet the standards of a Code Review answer, just like any other answer. Describe what you changed, and why. Code-only answers that don't actually review the code are insufficient and are subject to deletion.
   • Give credit to any other users who may have helped you. Posting a selfie that merely reiterates an existing answer without adding new insight would deprive another user of well deserved reputation. Also consider making your selfie community wiki if you feel that earning reputation from it would be unfair. Moderators may also activate community wiki status on self-answers at their discretion.

3. Sharing your code on an external site. If you are unwilling to write a sufficient explanation to constitute a good Code Review answer, then it would be best to refrain from posting your follow-up on Code Review at all. Instead, you may host your revised code on an external site (e.g. GitHub, GitHub Gist, Pastebin, JSBin, JSFiddle, Ideone, SQLFiddle, your personal blog, etc.) If your off-site host has revision capabilities, then include a link to the revision that was posted in the question. Format the edit as if it was always part of the question, and not as if it is an "Update." Something like the following:

   This code and updates are available at: [this repository](...some revision...)

   You could alternatively link to it in a comment on the question or in a comment on the most helpful answer.

Answer 2

The Help Center page and its Deficiencies

How do I write a good answer?

---

Thank you for taking the time to contribute an answer. It’s because of helpful peers like yourself that we’re able to learn together as a community. Here are a few tips on how to make your answer great.

What goes into an answer

Every answer must make at least one insightful observation about the code in the question. Answers that merely provide an alternate solution with no explanation or justification do not constitute valid Code Review answers and may be deleted. In addition to criticisms, pointing out good practices in the code is also a form of helpful feedback.

Answers need not cover every issue in every line of the code. Short answers are acceptable, as long as you explain your reasoning. Do not provide suggestions for improvements in a comment, even if your suggestion makes a very short answer.

Before answering

Not all questions can or should be answered here. Save yourself some frustration by flagging off-topic questions for closure instead. Also, if a question is ambiguous, it may be better to write a comment asking for clarification rather than writing an answer based on an incorrect assumption.

Read the other answers so you don't cover duplicate points. While it is fine to mention points in multiple answers, each answer should contain at least one novel observation.

Organizing your thoughts helps make your answer more readable by grouping related points together.

Tailor your advice to the apparent level of the author of the question, because our goal is to help programmers learn to improve.

Write to the best of your ability

We don't expect every answer to be perfect, but answers with correct spelling, punctuation, and grammar are easier to read and tend to get upvoted more frequently. Remember, you can always go back at any time and edit your answer to improve it.

Always be polite and have fun

It’s fine to disagree and express concern, but please be civil. There is a real human being on the other end of that network connection, however misguided they may appear to be. We are here to learn from our peers, not to yell at each other.

Answer 3

The Help Center page and its deficiencies and more

---

What questions can I ask about here?

Code Review is a question and answer site for seeking peer review of your code. We are working together to improve the skills of programmers worldwide by taking working code and making it better.

If you have a working piece of code from your project and are looking for open-ended feedback in the following areas:

• Best practices and design pattern usage
• Security issues
• Performance
• Correctness in unanticipated cases

… then you are in the right place!

---

If you can answer "yes" to all of the following questions, then your question is on-topic for Code Review:

• Is code included directly in my question?

  It is fine to post supplementary code on a third-party site, but the most important parts of the code must be embedded directly in the question.

  Code blocks can be created in Markdown using the { } button (Ctrl K) in the question editor. For JavaScript / HTML / CSS questions, you can create a live demonstration using the Stack Snippets button (Ctrl M).

• Am I an author or maintainer of the code?

  For licensing, moral, and procedural reasons, we cannot review code written by other programmers. We expect you, as the author, to understand why the code is written the way that it is.

• Is it actual code from a project rather than pseudo-code or hypothetical code?

  Details matter! In order to give good advice, we need to see real, concrete code, and understand the context in which the code is used. Generic code (such as code containing placeholders like foo, MyClass, or doSomething()) leaves too much to the imagination.

• To the best of my knowledge, does the code work as intended?

  Code Review aims to help improve working code. If you are trying to figure out why your program crashes or produces a wrong result, ask on Stack Overflow instead. Code Review is also not the place to ask for implementing new features.

  Questions about improving scalability are allowable, as long as your code works for small inputs.

• Do I want the code to be good code?

  It's OK to ask for help to optimize code to run in a resource-constrained environment. However, asking about code-golfing, obfuscation, or similar is off-topic.

• Do I want feedback about any or all facets of the code?

  Feel free to call attention to specific areas you are concerned about (performance, formatting, etc). However, any aspect of the code posted is fair game for feedback and criticism.

---

Other important information:

• Examples of questions to avoid asking
• After you receive answers, do not revise or incorporate new code into your question.

Answer 4

The Help Center page and its Deficiencies

How do I ask a good question?

---

Asking a question that is well-received by the community will get you more upvotes and quicker answers. Here are some tips for asking a successful question.

Be on-topic

Do not ask questions about broken code, hypothetical code, or non-existent code, as such questions will be closed as off-topic.

If you have a programming-related question that does not meet those requirements, then it is not suitable for Code Review. You might be able to ask it elsewhere.

Titling your question

State what your code does in your title, not your main concerns about it. Be descriptive and interesting, and you'll attract more views to your question.

Here are some examples of titles that are unacceptable because they are too generic:

• How can I make this faster? (Everyone prefers faster code. The (performance) tag can convey this desire.)
• Simplify this chain of if statements (Applies to too many questions.)
• Ruby function needs refactoring (Reviewers will decide if it needs refactoring. You don't have to ask for it in the title.)
• Is this good OOP design? (Title is not distinctive.)
• Online judge says Time Limit Exceeded (Title tells us nothing beyond what would be conveyed by (programming-challenge) and (time-limit-exceeded) tags.)

Furthermore, you should omit these kinds of superfluous phrases from titles, because these requests are implicit in every Code Review question:

• Can you critique my …
• Please help me…
• … needs improvement
• Reduce the complexity of…

The norm is to summarize the goal of the code in the title. Some typical titles are:

• Project Euler 9: finding a Pythagorean triplet
• Game of Life with a Swing UI
• View controller for smoking cessation iOS app
• Validating inputs for a vacation request form

If your code does not have a goal, then it is likely that your question contains hypothetical code, or that you are asking about best practices in general rather than for a review of your code. Such questions are off-topic for Code Review.

Asking your question

You will get more insightful reviews if you not only provide your code, but also give an explanation of what it does. The more detail, the better.

Also, tell us some background information. Why did you write the code? Is it an (interview-question)? Is it (homework), for which you would prefer not to have someone provide a completely rewritten solution? An online (programming-challenge) (in which case, please link to the challenge and include a summary of the challenge)? Are you a (beginner) picking up a new programming language? If you are deliberately reimplementing a common library function as an exercise, you should tag it as (reinventing-the-wheel) so that you can get reviews that are more insightful than "Hey, just use this standard function instead!"

Be sure to embed the code you want reviewed in the question itself; you can leave supporting, but non-essential, code in links to other sites. Strip out sensitive information such as passwords, but do not alter the code so much that it no longer resembles your original work.

Example of a poorly asked question

Can this SQL join be improved?

I have a query like this that seems complicated and is taking a long time to run. We're running this query in a loop, so speed is important. I'd like to see if any of you SQL experts can help me simplify it.

SELECT *
    FROM table_a a
        JOIN table_b b
            ON a.col1 = b.col1
            AND a.col2 = b.col2
            AND a.col3 = b.col3
    WHERE a.col1 = ... AND a.col2 = ... AND a.col3 = ...
        AND b.name = '...';

---

(sql)

Problems with this question include:

• Title: It states a concern about the code rather than the purpose of the code. It is also too generic to be distinct.
• Fuzzy language: What does "a query like this" mean? We can't tell which parts of your code are to be taken literally, and which parts are idealized.
• Hypothetical identifiers: What do table_a and table_b really contain? How about col1, col2, and col3?
• Lack of detail: Is this running on MySQL? Microsoft SQL Server? How many rows are involved, and how long is it taking? How are the relevant tables defined, and have you put indexes on the columns?

Here's an improved version of the question:

Finding incidents involving a particular server

This query is part of a PHP web application that our company uses internally for logging incidents on our machines. We have about 20000 rows in ServerEventLogs and 3000 rows in Incidents. The following query takes about 800 ms, which is too slow for a responsive UI, since we would usually have about 5 hosts per cluster.

$log_incidents = array();
for ($cluster_hosts as $hostname) {
    $res = mysql_query("SELECT *
        FROM ServerEventLogs log
            JOIN Incidents inc
                ON log.year = inc.year
                AND log.month = inc.month
                AND log.day = inc.day
        WHERE log.year = $year AND log.month = $month AND log.day = $day
            AND inc.hostname = $hostname;");
    $log_incidents[] = logIncidentToJson($res);
}

---

(php) (mysql) (sql) (join) (datetime)

The added detail makes a big difference in the quality of the advice that reviewers can provide. For example, the fact that col1, col2, and col3 are actually fields in a date can mean that we can take advantage of MySQL's datetime support.

Answer 5

The Help Center page and its Deficiencies

---

What are tags, and how should I use them?

A tag is a word or phrase that describes the topic of the question. Tags are a means of connecting experts with questions they will be able to answer by sorting questions into specific, well-defined categories.

Tags can also be used to help you identify questions that are interesting or relevant to you.

Clicking on a tag below a question brings you to a page that shows all questions within that tag. You also see a description of what the tag is and how it should be applied on Code Review Stack Exchange (since sometimes the tag name is a common word that has a broad meaning in the real world but a very particular, narrow meaning on this site.) These descriptions comprise the tag wiki, which is editable by the community like any other post.

As a general rule, you should avoid creating new tags if possible, and new users are not allowed to create new tags. Even if you have sufficient reputation, you should only create new tags when you feel you can make a strong case that your question covers a new topic that nobody else has asked about before on this site.

Each question may only contain 5 tags at a maximum, so choose the ones that best describe your question. Spaces are not allowed in tags – create compound tags using hyphens rather than spaces (like [visual-studio]) rather than multiple tags separated by spaces ([visual] [studio]).

How to format tags

• Use all lower case
• Replace spaces with hyphens (-) to combine multiple words into a single word (e.g., tag "unit testing" as unit-testing)
• Avoid punctuation (which can make it difficult to use the tag in a URL)
• When naming a tag, think about how someone would search for that subject. In most cases this means typing out the full name, but you may also want to use the abbreviation. For example, [css] is probably more appropriate than [cascading-style-sheets]

Re-tagging

As part of the editing process, users may suggest edits or directly edit the tags of a question if they feel a certain tag was used inappropriately or that the question is missing a tag.

You should re-tag questions when:

• You are adding valuable information to the question by doing so
• You are replacing obscure or difficult to understand tags with well-known and popular tags that are appropriate for the question.

Avoid meta-tags

Do not use meta-tags in questions. Here are some tips to help you determine whether a tag is a meta-tag:

• If the tag can’t work as the only tag on a question, it’s probably a meta-tag. Every tag you use should be able to work, more or less, as the only tag on a question. Meta-tags, like [beginner], [subjective], and [best-practices], are not helpful by themselves – they do not communicate anything about the content of the question.
• If the tag commonly means different things to different people, it’s probably a meta-tag. For example, the meaning of the tag [subjective] is, itself, subjective; the same is true for tags like [best-practices] and [beginner]. Best practices to whom? Beginner by what criteria? Use only tags that have a broadly accepted, objective definition.

Should I use tags in titles?

You should not force a tag into your title. Because the tags appear below the question and tags are indexed by search engines along with the content of your question, you can trust that other people will be able to find your question based on tags they follow or search for. Additionally, tags appear on the question page, so other people will take them into account when answering your question.

Avoid inserting tags into titles in any of the following formats:

• [tag]: [question title]
• [question title] -- [tag] [tag] [tag]
• [question title] in [tag]
• [tag] [tag] [question title] [tag] [tag] [tag]
• [tag] [tag] [tag] [tag] [tag] [tag] [tag] [tag]

The only time you should use tags in your title is when they are organic to the conversational tone of the title.

For example, rather than writing, "JavaScript, jQuery: When should I use one or the other?" – which forces tags into the title – you can convey the same information in a conversational tone:

Can I use jQuery to foo the bar on the baz, or am I stuck using plain JavaScript?

Answer 6

The Help Center page and its Deficiencies

---

What should I do if no one answers my question?

First, make sure you’ve asked a good question. To get better answers, you may need to put additional effort into your question. Edit your question to provide status and progress updates. Document your own continued efforts to answer your question. This will naturally bump your question to the homepage and get more people interested in it.

If, despite your best efforts, you feel questions aren’t getting good answers, you can help by offering a bounty on any question more than two days old or bring it up in The 2nd Monitor (you will need 20 rep to chat).

Answer 7

The Help Center page and its Deficiencies

What types of questions should I avoid asking?

---

First, make sure that your question is on-topic for this site. In short, questions seeking open-ended feedback on real working code that you own or maintain are on-topic for Code Review.

Here are some examples of questions that are unsuitable for Code Review.

Troubleshooting, debugging, or understanding code snippets

Code Review is for open-ended questions about code that already works correctly (to the best of your knowledge). Questions seeking help about debugging or understanding code are off-topic for Code Review, and may be on-topic for Stack Overflow.

Best practices in general

It's OK to ask "Does this code follow common best practices?", but not "What is the best practice regarding X?" Questions should not contain purely generic, hypothetical code, such as

if condition_a:
    do_something()
else if condition_b:
    do_something_else()
else:
    do_something_even_different()

Also watch out for hypothetical wording, such as "Imagine" or "Let's say we have…"

Higher-level architecture and design of software systems

We review code, not concepts, diagrams, or outlines. Whiteboard-style questions may be suitable on Software Engineering if they are specific.

Tools and tips for conducting code reviews

Questions about code review methodology should be asked on Software Engineering.

For questions about the Code Review site itself, please visit our meta-discussion site, where you can talk about things like what questions are appropriate and what tags should be used, suggest features, point out bugs, or generally discuss how this site works.