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\$
5
  • 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, 2014 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, 2014 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, 2014 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, 2014 at 18:16
  • \$\begingroup\$ Printable PDF of the accepted answer \$\endgroup\$ Aug 23, 2014 at 10:33

2 Answers 2

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\$
6
  • \$\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, 2014 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, 2014 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, 2014 at 20:52
  • \$\begingroup\$ Here's a screenshot of this taken from the page source. \$\endgroup\$
    – Jamal
    Aug 6, 2014 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\$ Aug 7, 2014 at 15:10
  • 1
    \$\begingroup\$ @Bhathiya-JaDogg-Perera: I'll make some more additions here soon. \$\endgroup\$
    – Jamal
    Aug 10, 2014 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 .