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., "
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)
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.
Many books have a separate text style to highlight GUI elements. For example: “Select the
Save As... item from the
File menu.” or “Select
Save As...” Perhaps, these things could be highlighted with the inline code spans too.
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).”
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
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)
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
City columns from the
- 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.