86

I reviewed an edit that did no change to the post apart from introducing code formatting like this to words that aren't code, such as iOS and Android (while curiously leaving Delphi untouched). I didn't really see the point of this so I rejected the edit as too minor, only to see it had already been approved.

Is there some guideline that OS names should use code formatting? To me, it seems the change does little to improve the post and shouldn't have been approved, but since several reviewers disagreed I believe I should ask it here.

Return to FAQ index

0

2 Answers 2

163

Code formatting shouldn't be used for emphasis on regular words. That includes technology names like "iOS", "GitHub", "C#", or any other proper nouns; they don't need any special formatting. Overuse could make your post less readable. As for what it should be used for:

Inline code formatting can be useful for:

  • Micro-snippets of code (This is especially important for HTML tags or things that resemble HTML tags, since some HTML is allowed in posts and the site will try to render anything between < and >)
    • init()
    • if (boolean) {
    • <form action="..." method="post">
    • <strong>
    • <level>
    • &nbsp;
  • Filenames and filepaths
    • readme.txt
    • .htaccess
    • C:\windows\system32
    • __init__.py
  • Shell commands, or executable names written as you'd write them at your terminal:
    • git
    • cp file1.txt file2.txt
  • Showing a URL that you don't want to render into something clickable
    • http://www.example.com
  • Data
    • form input values
    • text that an algorithm will operate on
  • Short errors
    • AttributeError: 'super' object has no attribute '__getitem__'.

Code block formatting can be useful for errors and logs, especially when:

  • They're meant to be in a monospaced font

    01-25 22:13:18.594: DEBUG/skia(4204): xxxxxxxxxxx jpeg error 20 Improper call to JPEG library in state %d
    01-25 22:13:18.604: INFO/System.out(4204): resolveUri failed on bad bitmap uri: 
    01-25 22:13:18.694: ERROR/dalvikvm-heap(4204): 6291456-byte external allocation too large for this process.
    01-25 22:13:18.694: ERROR/(4204): VM won't let us allocate 6291456 bytes
    01-25 22:13:18.694: DEBUG/skia(4204): xxxxxxxxxxxxxxxxxxxx allocPixelRef failed
    
  • They contain spacing that is lost if it isn't pre-formatted

    Traceback (most recent call last):
      File "x.py", line 6, in <module>
        f(a=1, b=1)
      File "x.py", line 4, in f
        return 1 / (a+1) + 1 / (b-1)
                           ~~^~~~~~~
    ZeroDivisionError: division by zero
    

Just make sure to disable syntax highlighting:

```none
your logs/errors here
```

(Also consider using quote blocks instead, especially for long single-line error messages.)


Beyond these examples, use other, more suitable formatting.

So for example, don't use code formatting for:

  • Emphasising words.
    Use italic or bold text instead (sparingly).
  • Keyboard keys.
    Use the <kbd> tag.
  • Tables.
    Use proper Markdown tables instead
75
  • 1
    The error code example is about code blocks, but everything else, including the question, appears to be discussing inline code spans. Should that really be included in this answer (and/or should a single-line example be chosen)?
    – M. Justin
    Commented Jan 15, 2021 at 23:41
  • 3
    @M.Justin Already covered in the answer by "Micro-snippets of code". Let me move that item up to the top of the list, though. Also, the indentation here was apparently broken by the CommonMark migration, so I've fixed that, too.
    – Cody Gray Mod
    Commented Jan 16, 2021 at 0:57
  • 4
    I find it's a good way to indicate search strings without confusion about punctutation marks, e.g.: Have you tried using <your favorite search engine> to look for wombat query vms? Searches for bacon levitation and "bacon levitation" tend to be quite different.
    – HABO
    Commented Jan 17, 2021 at 4:21
  • 2
    The style I've settled on for writing documentation/instructions is to use monospace text to indicate UI elements or other text the user might encounter (e.g. "Click the OK button to close the Preferences dialog"), and I've carried that over to Stack Overflow/Exchange. Care must be taken and context must be given to adequately separate it from actual code so it's not mistaken as such, but I think monospace makes more sense for that purpose than using "quotes" and especially bold or italics. Commented Apr 1, 2022 at 21:36
  • 4
    A couple specific ideas for Python: 1) use backticks for the name of a third-party package or tool as it would appear in the source code, such as in an import statement; or on a command line: "run pip install -e .". Use normal formatting for a package or tool as it would appear in documentation: "use Pip to install the package". 2) use backticks for the word "class" when specifically referring to the relevant code: "since Example was defined as a class, ..." / "since Example was defined using the class keyword, ..." Use plain text more generally: "since Example is a class, ...". Commented Dec 25, 2023 at 19:44
  • 1
    @wjandrea don't suggest keyboard keys here. This answer is about code formatting, not about keyboard key formatting.
    – Cerbrus
    Commented Jan 7 at 20:07
  • 1
    @Cerbrus I see your point, but it's specifically not about code formatting, it's about formatting non-code as if it were code. It'd be clearer if I wrote "For keyboard keys, it's fine, but it's better to use the <kbd> tag". How would you feel about that?
    – wjandrea
    Commented Jan 7 at 20:24
  • 1
    I'm considering filling in some details but I'm not sure everyone would agree. LMK: 1) Why not: It's not any clearer. The formatting is just a distraction. 2) What to use instead: Bold or italics can be used to add emphasis if necessary. In the edit OP's referring to, it's not. I see a lot of edits like this where people add code formatting to key terms (I guess), but 90% of the time, they don't need emphasis. Sometimes, BTW, terms can be confused with code, like if you write "iterator" in a Python question, could you be referring to collections.abc.Iterator?
    – wjandrea
    Commented Jan 8 at 2:28
  • 2
    @TylerH Sorry, what? This question is about formatting non-code as code and this answer includes filenames and URLs.
    – wjandrea
    Commented Jan 8 at 16:32
  • 1
    @bad_coder Done. I added a section about other cases where code formatting ideally shouldn't be used on non-code. No link though cause I couldn't find anything specific enough from a quick look.
    – wjandrea
    Commented Jan 8 at 21:21
  • 1
    🚽You could also wrap them in emojis, but you probably shouldn't.🧻
    – Kevin B
    Commented Jan 8 at 22:33
  • 2
    @Cerbrus I don't agree. It's not clear if that large notice is meant to mean that literally any other use of backticks is inappropriate, and either way is problematic. If it does mean that, it's wrong, since other accepted uses exist (one of which you just edited out!). If it doesn't, this post simply doesn't answer whether backticking technology and language names is appropriate, despite having been used as a dupe target multiple times for that precise question. Yes, it's an FAQ entry, and for that reason it should exhaustively cover at least the things that are frequently asked about!
    – Mark Amery
    Commented Mar 24 at 19:41
  • 2
    Like, literally what's the point of having an FAQ entry for this and using it as a dupe target if we're just gonna provide a partial answer, shrug and decide it's long enough, and roll back attempts to make it more exhaustive? It'd literally be more useful for this entire Q&A to not exist if we approach it like that, since at least then it wouldn't be used as a basis for closing other questions! We need to be able to document the answers to recurring policy questions somewhere.
    – Mark Amery
    Commented Mar 24 at 19:48
  • 2
    @Cerbrus I see your latest edit - looks good to me. I think we've grumpily haggled our way into producing something significantly better than what either of us originally wanted, so, thank you! (I am still not a big fan of the giant heading but I can live with it and many of the other changes you've either made or nudged me into along the way are big improvements on my first draft from earlier today.)
    – Mark Amery
    Commented Mar 24 at 21:52
  • 2
    Let's grumpily shake hands on a job well done, then @MarkAmery. The header was quite important to me, as that's a big signpost stating "Hey, we have formatting documentation" :D
    – Cerbrus
    Commented Mar 24 at 21:55
60

Code formatting should never be used for non-code text, except in very limited circumstances such as filenames, URLs, etc.

The use of backticks to emphasise individual words is especially pernicious.

Any suggested edit that adds such formatting should be rejected.

If you see any posts that use it edit it out along with fixing as many of the other problems with the post as you can.

1
  • 4
    "such formatting should be rejected", we could rather improve the edit using bold to emphasize and italic for special terms or titles, the HTML-kbd tag for shortcuts like <kbd>Shift</kbd>.
    – hc_dev
    Commented Jan 5, 2023 at 20:23

You must log in to answer this question.

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