16
\$\begingroup\$

I have seen that moderators work hard to format questions and answers.

Is there a check list they use (specially for CR), so others can also contribute by editing or properly formatting their own questions or answers?

\$\endgroup\$
  • 3
    \$\begingroup\$ Everyone is free to format the post as they see fit (as long as it's still clean and does not take away the meaning of the post), but I can provide my own "checklist" anyway. \$\endgroup\$ – Jamal Aug 6 '14 at 17:53
  • 2
    \$\begingroup\$ I think that would be very helpful to those of us who are trying to help you edit @Jamal. \$\endgroup\$ – RubberDuck Aug 6 '14 at 17:55
  • \$\begingroup\$ @Bhathiya-JaDogg-Perera: I've removed those links as they're not really part of this checklist (you were merely pointing out that they're not relevant). \$\endgroup\$ – Jamal Aug 6 '14 at 18:02
  • 3
    \$\begingroup\$ I generally just look for typos and grammatical errors, also vague titles like How can I make this code better? \$\endgroup\$ – Phrancis Aug 6 '14 at 18:16
  • \$\begingroup\$ Printable PDF of the accepted answer \$\endgroup\$ – 422_unprocessable_entity Aug 23 '14 at 10:33
23
\$\begingroup\$

After editing many posts over time, I've come up with my own checklist for formatting posts:

(I'll edit this as more things come to mind)

Code

  • Any code must be indented (manually, CTRL+K, or the {} button in the editor), not formatted with <code>/<pre>. These tags often leave extra whitespace, and if used incorrectly, hides syntax-highlighting. If you're unsure if it's being used, click on "edit" to make sure.
  • If a long piece of code is surrounded by backticks and wraps to the next line, it is often helpful to remove the backticks and apply indentation so that it can stand on its own line. This is mainly un-ideal if the flow of the sentence can become disrupted by doing this.
  • If code appears right after a list (but doesn't belong to the list), then even if the code is indented, it will be rendered incorrectly. Either some important text (no fillers) should be added in between, or <!--- ---> must be added to fix this.
  • If code inside a list shows up improperly, then it wasn't indented enough. Code within lists must be indented by eight spaces (more spaces required for more nesting, but always check the preview to make sure it's being done right).

Blockquotes

  • A programming challenge description
  • Code not to be reviewed (i.e. code taken as reference)
  • Input/output
  • Pseudocode
  • Documentation
  • A large quote by someone
  • Optional (for answers): blockquoting the referenced code from the question

Lists

  • Questions can be numbered or bulleted
  • If "1)" is used for numbering, replace with "1." to properly format it as a numbered list item. However, if code will immediately follow (no text to put on the same line as the number), then it may not be ideal to change this. It doesn't have to be forced if it'll require noisier changes.

Noise (which I remove):

  • "Hi"/"hello"/"greetings"...
  • "Thanks"/"thanks in advance(d)"/"thx"...
  • "Here's my code:" (if it's obvious that it's the OP's code)
  • "EDIT:" (unless it's really needed)
  • "guys" (not a gender thing; it just sounds informal)
  • "Sorry for my English" (we know that not everyone speaks it well)
  • "I'm not sure if this belongs here" (we'll determine that)
  • "I was told to come here" (okay, good to know, but it's irrelevant)
  • "Please add [tag]" (the tag(s) can be added by someone if needed)
  • "Please let me know if you need more information" (this will be done if needed)
  • "How can I improve this code" (already implied on this site)
  • "0 downvote favorite" (copy/paste error; absolute noise)
  • Excessive caps, bold, italics, and large text (only emphasize what's really needed)
  • Use of backticks for anything but inline code (replace with other formatting)
  • Blatant tags in titles (such as "C++: sorting algorithm")

Syntax-highlighting

  • If something is formatted as code which isn't code (i.e. a program's output), then the following should be applied above the text to remove the syntax-highlighting:

    <!-- language-all: lang-none -->
    
  • If a post contains snippets of multiple languages, and the syntax-highlighting is mixed (i.e. JavaScript highlighting being applied to HTML code), then they should be fixed as such (depending on the languages in question):

    <!-- language-all: lang-js -->
    
    // JavaScript code...
    

    <!-- language-all: lang-html -->
    
    // HTML code...
    

Misc.

  • Appended improved code should be removed (see this)
  • Replies to a comment or answer should be removed (if added to the question or another answer)
\$\endgroup\$
  • \$\begingroup\$ @Bhathiya-JaDogg-Perera: It's some weird copy/paste thing. I can't quite seem to find the relevant post about this, though. \$\endgroup\$ – Jamal Aug 6 '14 at 19:59
  • \$\begingroup\$ @Bhathiya-JaDogg-Perera: I don't particularly focus on ordering, which is why it wasn't included here. \$\endgroup\$ – Jamal Aug 6 '14 at 20:00
  • 1
    \$\begingroup\$ @Bhathiya-JaDogg-Perera it's what you get if you select the voting div by a question. Right now, for this question, I get 6 down vote favorite 1. \$\endgroup\$ – Schism Aug 6 '14 at 20:52
  • \$\begingroup\$ Here's a screenshot of this taken from the page source. \$\endgroup\$ – Jamal Aug 6 '14 at 21:42
  • \$\begingroup\$ Can you add this too : language need not be explicitly specified when the appropriate language tag exists first on the question. Credits: Schism \$\endgroup\$ – 422_unprocessable_entity Aug 7 '14 at 15:10
  • 1
    \$\begingroup\$ @Bhathiya-JaDogg-Perera: I'll make some more additions here soon. \$\endgroup\$ – Jamal Aug 10 '14 at 5:25
2
\$\begingroup\$

For a question (Sample) :

I prefer to break the question into multiple chunks, I use Simon's Review Prepare if possible.

  1. Description
    1. Input and Expected Output
    2. Versions and Dependencies
  2. Code
    1. GitHub or other downloadable links
    2. Live preview links
    3. Related Code

      SimpleSentence.java: (34 lines, 971 bytes)

  3. Unit Tests

    SimpleSentenceTest.java: (74 lines, 2666 bytes)

  4. Other Resources Needed to run the application

    pom.xml: (23 lines, 917 bytes)

\$\endgroup\$

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .