12

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?

  • 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
  • 8
    @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
  • 2
    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
19

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.
  • 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
  • <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
6

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 w3 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 unfortunatly doesn't work on SE.

  • +1 but I will wait for more answers before accepting one. – Alexey Jan 9 '14 at 3:37
  • 1
    Kapep's use of the inline elements in his answer are good examples of proper usage. – Robert Harvey Jan 9 '14 at 21:57

You must log in to answer this question.

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