17

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?

7
  • When someone asks a question, a "popup" displays some help with the title "How to Format". However, you can then click/visit the formatting help center to see what kinds of formatting is available/suggested. Specifically, see Code and Preformatted Text. – Werner Jan 9 '14 at 0:57
  • 10
    @Werner Your links explain how one can make an inline code span (put it in backticks). But the question is what things should be put in inline code spans. – Alexey Jan 9 '14 at 1:05
  • 3
    Ideally, the name "Inline Code Span" would indicate their usage clearly enough; they're for spanning code, in situations where that code is inline. Unfortunately, some people can't see a clue-by-four when you're literally hitting them with it, a brief guideline on the formatting help center would probably help. – Billy Mailman Jan 9 '14 at 2:27
  • @bfavaretto Thanks, I will have a look at these links in a minute, but at the first glance they cannot be used for instructing new users. – Alexey Jan 9 '14 at 2:54
  • It balances out against users who insist that backticks are better than bold or italics for some reason – random Jan 9 '14 at 2:57
  • @BillyMailman I think that monospace formatting can be useful for some other things too. For example, have a look at this question that I formatted a few days ago (I used the inline code spans to highlight commands). Have a look in its edit history to see what it looked like before the edit. – Alexey Jan 9 '14 at 2:59
21

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.
5
  • 2
    Related to the part about gui elements: meta.stackexchange.com/q/215133/230957 – 3ventic Jan 10 '14 at 0:20
  • 1
    @3ventic I did not know about the <kbd> tag. Perhaps it can be used to format GUI elements. But they did not come to any final conclusion in that question. – Alexey Jan 10 '14 at 0:40
  • 1
    <kbd> is probably useful for highlighting keyboard keys. They are not "strings recognized by a computer", and there is a consent about the use of <kbd> for this purpose on SO. – Alexey Jan 11 '14 at 9:57
  • I'd disagree about file names. They are often used in code and passed to programs as parameters but are not code. All sequences are valid computer code somewhere, e.g. echo I like bananas >> diet_prefs.txt. True, writing diet_prefs.txt may aid readability and is more appropriate than writing I like bananas. That's because file name, diet_prefs.txt, is more closely related to computer code than English clause, I like bananas. Nevertheless, neither are code and therefore writing diet_prefs.txt is inappropriate. – John McFarlane Jan 24 '16 at 20:54
  • The HTML Living Standard says that filenames can be marked up with <code>: "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." – David J. Feb 5 at 15:38
7

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.

2
  • 1
    Kapep's use of the inline elements in his answer are good examples of proper usage. – user102937 Jan 9 '14 at 21:57
  • 1
    Yes, the samp element is perfect for log output, given what the WHATWG HTML Living Standard says: "The samp element represents sample or quoted output from another program or computing system." IMO, <samp> is not widely enough known and underutilized. – David J. Feb 5 at 15:53
1

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.

4

You must log in to answer this question.

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