Is there a page that explains how inline code spans should and should not be used?

Question

I have done some reviews of new user's questions recently, and I noticed that most of these posts do not use inline code spans (e.g., "the main() method", "the HelloWorld class") - the things formatted with backticks (`).

Does SO have a page/question where you can redirect someone to explain what the inline code spans are, and how they should be used (preferably with examples)?

I found this question: Inline Code Spans should not be used for emphasis, right? There is a good answer there which says that inline code spans should be used for "code and code-like artifacts". However, that question is about a different thing, and many people may still wonder what a code-like artifact is. For instance, file names or fragments of a log file are often formatted as inline code spans, but they, probably, cannot be called "code-like artifacts". There are other examples that may look confusing.

In other words, many programming books have a typographical conventions section which explains how the book uses special text styles. Does SO have something similar which explains the use of the inline code spans?

Answer 1

As nobody mentioned any existing conventions on the use of the inline code spans, I decided to post my own response. Though the other answer is good, I hope I can provide more details. The content of this response is just my personal opinion. It summarizers my experience. I hope someone will find it useful.

When the inline code spans should be used

Any string that can be recognized or generated by a computer usually is highlighted in a text. As SO has only one text style for this purpose (the inline code span), I use the inline code spans to highlight all such strings when I write SO posts. In my own documents, I usually make only one exception: I use a separate text style to highlight GUI elements (e.g., "File > Open...").

When the inline code spans should NOT be used

Strings that can only be used in documents intended for human interpretation (e.g., trademarks, names of software packages, programs, libraries, technologies, abbreviations) are not highlighted as inline code, though they can have other styles applied to them. Some examples: HTTP, TCP/IP, HTML, CSS, AJAX, SQL, Linux, C++, .NET, SaaS, Spring Framework, LibreOffice, iPhone, jQuery, GUI.

Strings recognised or generated by a computer

• medium size code fragments (e.g., SELECT * FROM MyTable, this.id = id;)
• (the name of) a class, method, statement, variable, method parameter, string constant, file, file path, file extension, command, HTML tag, SQL statement, fragment of a configuration file, etc.
• input of a program (e.g., a value entered by a user)
• output of a program (e.g., a fragment of a console output, a fragment of a log file)

Dual cases

There are some dual cases: “gedit” is a name of a popular text editor but it's also a command that starts the editor. As a name of a program it should NOT be highlighted, but as a name of a command interpreted by a computer it should. Probably, the formatting depends on the sense in which you use the word.

Other typographical conventions

Books on programming often have a typographical conventions section that explains how the book uses different text styles. These conventions are more complex than the one described here. For example, user input and output of a program may have their own styles. However, SO does not have text styles to accommodate all these things separately. Besides, writing posts or documents using too many styles can be laborious.

GUI elements

Many books have a separate text style to highlight GUI elements. For example: “Select the Save As... item from the File menu.” or “Select File > Save As...” Perhaps, these things could be highlighted with the inline code spans too.

Articles

Using articles (a, an, and the) before code-like artifacts can be a challenge for people whose first language does not have them (articles). Naturally, neither English grammars nor books on programming address issues like “using articles before SQL/Java statements”.

When an inline code fragment is followed by a word that says what sort of thing the code fragment is, the article “the” is usually used before the fragment. For example: “The HelloWorld class has three methods.”, “Open the readme.txt file”. But indefinite article (a/an) can also be used in a number of cases: “There is a <p> tag in the document.” Usually there is at least some article.

When an inline code fragment is used on its own, often it does not have an article at all: “HelloWorld has three methods.”, “Open readme.txt.” I think, in this cases the author considers them to be proper names (which do not need articles). However, sometimes there is an article anyway: “The DispatcherServlet is an actual Servlet (it inherits from the HttpServlet base class).”

Quotes

There is no need to put inline code fragments in quotes as they are already highlighted. However, string constants can keep their delimiters to separate them from other things. For example: “The sayHello() method returns “Hello World!”.”

Examples

Java (examples from http://docs.oracle.com)

• String conversions are implemented through the method toString, defined by Object and inherited by all classes in Java.

• Unless otherwise noted, passing a null argument to a constructor or method in this class will cause a NullPointerException to be thrown.

• All string literals in Java programs, such as "abc", are implemented as instances of this class.

HTML/CSS (examples from http://www.w3schools.com)

• HTML paragraphs are defined with the <p> tag.

• The background-color property specifies the background colour of an element.

SQL (examples from http://dev.mysql.com, http://www.w3schools.com)

• SELECT is used to retrieve rows selected from one or more tables, and can include UNION statements and subqueries.

• This SQL statement selects the CustomerName and City columns from the Customers table.

Commands

• Normally, if sudo requires a password, it will read it from the user's terminal. If the -A option is specified, a helper program is executed.

Answer 2

I haven't seen any official guideline for this yet. My rule of thumb is, if something will at some point get parsed somehow (like commands, URLs, file names etc.) it is code-like in most contexts.

We all like semantically correct HTML, so I would also take a look at the W3C HTML5 specification of the <code> element, which is used to wrap the inline code. The definition of "code" is very broad here and especially the last part probably includes what is meant by "code-like":

The code element represents a fragment of computer code. This could be an XML element name, a file name, a computer program, or any other string that a computer would recognize.

I can't really argue about log output, even though when I usually see something in a monospaced font, I would expect it to be monospaced in a post too. The <samp> element would be appropriate but unfortunately doesn't work on SE.

Answer 3

I have not seen an official Stack Overflow (or sibling site) page that describes the various ways to use inline code spans.

The StackOverflow Community: a mix of consensus and disagreement

How should inline code blocks be used? In this section, I'll share my experience based on observing what experienced SO users tend to say.

There is wide consensus on using inline code blocks for:

• identifiers (i.e. constants, variable names, function names)
• expressions (e.g. 1 + 2)

There is some disagreement about using inline code blocks for:

• filenames
• keystrokes
• program output

Authoritative Recommendations

How should inline code blocks be used? What other HTML elements are available? In this section, I'll summarize what authoritative sources say about the uses mentioned above.

The following table summarizes appropriate HTML elements for certain uses, based on WHATWG and MDN. You can find more detailed quotes in later sections.

use	HTML element	rendered examples
identifier	<code>	foo, Math.PI
expression	<code>	min(x, y)
filename	<code>	robots.txt
program output	<samp>	Processes: 547 total
keystroke	<kbd>	CTRLA

I recommend using this table as part of the documentation for newer users.

Note: Web standards change over time. As of this writing, the table accurately conveys the recommendations of WHATWG and MDN. I've found that both are comprehensive, reliable, accepted, and useful.

The code element

From the WHATWG HTML Living Standard documentation of the code element:

The code element represents a fragment of computer code. This could be an XML element name, a file name, a computer program, or any other string that a computer would recognize. (4 February 2021 version)

<samp>

From the MDN documentation of the samp element:

The HTML Sample Element (<samp>) is used to enclose inline text which represents sample (or quoted) output from a computer program. Its contents are typically rendered using the browser's default monospaced font (such as Courier or Lucida Console).

Update: As mentioned in the comments, <samp> is not currently supported by Stack Exchange sites. If you use it in an answer, it will be stripped out. I would ask for your help in addressing this limitation to move SE sites towards better HTML support.

<kbd>

From the MDN documentation of the kbd element:

The HTML Keyboard Input element (<kbd>) represents a span of inline text denoting textual user input from a keyboard, voice input, or any other text entry device. By convention, the user agent defaults to rendering the contents of a element using its default monospace font, although this is not mandated by the HTML standard.

Focus on markup first

In this section, I'll offer a broader context than just the inline code tag. Let's start with the MDN accessibility documentation:

A great deal of web content can be made accessible just by making sure the correct Hypertext Markup Language elements are used for the correct purpose at all times.

Doing accessibility well means focusing on markup and letting the user agent (i.e. a browser) handle the presentation.

So, I suggest:

• Strive for the best markup available for the given context.
• Be humble.
• Your current knowledge may be incomplete and/or wrong.
• Read about accessibility and stay up to date.
• If you don't know about an HTML element, you probably aren't going to use it well.

Semantics over presentation

This section offers a different lens on the previous section.

Whenever possible, focus on semantics rather than presentation details.

An example semantic question is: "How do I markup a log file?". This should motivate you to use the <samp> element, based on the WHATWG guidance (shown above).

An example of a presentational question is: "How do I get a monospace font with a gray background?". This question does not necessarily imply that <code> is the correct choice. Instead, you should make sure you understand the range of HTML tags available and choose an element that matches the semantics.

Some may disagree

As I said in the first section, I know some some people have different opinions. If you want to contribute to the conversation, please cite your sources and rationale.