28

I've been following this "When should code formatting be used for non-code text? " post for guidance on removing backticks when reviewing suggested edits as well as when forming my own questions and answers. I have one nagging grey area not specifically addressed in this post or elsewhere that I'd like guidance on...

Is it appropriate to use backticks to emphasize references to things that can appear in code? Are these themselves code? If they are not, is it still appropriate to emphasize them with backticks? I'm talking about stand-alone (not within a larger code block) references to things like:

  • ClassNames
  • variableAndMethodNames
  • SYMBOLIC_CONSTANTS
  • "literals"
  • imported package.or.library.names

For example:

You should be passing your `someMethod` method of your `SomeClass` class the value `"a way cool string literal"`.I'

or in rendered form:

You should be passing your someMethod method of your SomeClass class the value "a way cool string literal".

Is this sort of thing an appropriate use of backticks? Any other guidance?

5
  • 18
    Not only is this appropriate, it is the primary intended use of backticks / inline code spans. I wouldn't characterise it as "emphasiszing" these things, though.
    – Mark Amery
    Commented Apr 5, 2019 at 10:31
  • 8
    All those things don't belong to "non-code text". They are code text.
    – Bergi
    Commented Apr 5, 2019 at 15:56
  • Thanks for your opinion @Bergi. That's just what I was asking. If you look again, you'll see that I ask exactly the question you are answering in my post.
    – CryptoFool
    Commented Apr 5, 2019 at 16:12
  • One thing that isn't well documented, services like Google Translate won't translate text between backticks; considering most programming languages aren't localized, it would probably be a good idea to put anything code related (e.g., class names, function names, etc) in backticks. E.g., you don't really want string (as in std::string) to get translated to cuerda, if you write string instead it will always show up as string.
    – jrh
    Commented Apr 5, 2019 at 21:04
  • Oy. I'm guessing that formatting purely to avoid translation is a can of worms best left closed given the sensitivity of this issue already. Hopefully, that will come as a natural side effect of applying the other guidelines we've been discussing.
    – CryptoFool
    Commented Apr 5, 2019 at 21:18

2 Answers 2

45

Yes, this usage is acceptable. Identifiers that are found in source code are code, and therefore it's acceptable to format them as if they are code.

The rule is, inline code formatting is only for code—never for emphasis, or proper nouns, or anything else that isn't actually code.

The only one of your examples I'm not wild about is formatting string literals as code. I think the fact that they're surrounded by quotation marks is sufficient demarcation. At least don't use inline code formatting for long strings.

Also note that there is a concern beyond strict semantics: readability. if you have a paragraph where you make reference to a lot of identifiers (function names, keywords, constants, etc.), formatting each of those identifiers using inline code formatting can actively interfere with readability. Thus, you need to use it sparingly.

Consider:

In order to foo the bar, you first need to call PrepareBar(), passing in a const reference to the bar. Make sure that bar is of type IFooableBar and that you've created it using the MAKE_FOOABLE constant.

versus:

In order to foo the bar, you first need to call PrepareBar(), passing in a const-reference to the bar. Make sure that bar is of type IFooableBar and that you've created it using the MAKE_FOOABLE constant.

The meaning of these is equally clear, but I'd argue that the latter is significantly easier on the eyes. You don't have the big, ugly, gray blocks breaking up the flow of the text.

If I were writing this as an answer, I'd probably use an intermediate formatting style, where I set only bar in inline code formatting:

In order to foo the bar, you first need to call PrepareBar(), passing in a const-reference to the bar. Make sure that bar is of type IFooableBar and that you've created it using the MAKE_FOOABLE constant.

The SCREAMING_CASE and function-call parentheses make it sufficiently obvious that these are identifiers found in code; special formatting is not required, and can be omitted in the interest of readability. However, bar is special, yet it looks too much like normal text, so I'd format it in such a way to make it obvious that it is a specific identifier in the source code.

As I stated at the beginning, this is not a semantic argument, but a practical one. If inline code formatting wasn't so ugly, the readability problem would be diminished. But it is what it is, so this is a choice that authors should be allowed to make. Please don't go through other people's posts and apply inline code formatting to every symbol. It was very likely a deliberate choice to eschew it.

13
  • 2
    Wow, thanks @CodyGray! This is perfect. Assuming someone else doesn't come along and disagree strongly with your suggestions, I'll go with them. I totally get the idea that too much of any good thing can be not a good thing. I also agree about the string literals. - btw, I'm asking this more for use when I'm editing existing posts or reviewing proposed edits. For my own content, I tend to err on the side of very minimal use of emphasis. I only emphasize things I think are the one or two key ideas of my post. ...
    – CryptoFool
    Commented Apr 5, 2019 at 5:01
  • I read somewhere (maybe in the post I reference) that you should ask yourself "if I could only emphasize one or two words, would this be one of them?". That's what I tend to do for my own posts. But I don't want to be that strict when editing someone else's work.
    – CryptoFool
    Commented Apr 5, 2019 at 5:03
  • 6
    Emphasis has nothing to do with inline code formatting, @Steve. I'm troubled that you seem to be using them interchangeably. If you want emphasis, you use bold or italics. Yes, those should also be using sparingly. If you emphasize everything, nothing is emphasized anymore.
    – Cody Gray Mod
    Commented Apr 5, 2019 at 5:03
  • I'm talking about the use of bold and italics as well. Don't worry. Nobody's had any problem with my posts once I was corrected on the use of...well...backticks :( . So there is just one key point here, and that would be if the references I'm talking about must be put in backticks. I have been considering this sort of backticking to be emphasis. I will at times not put these terms in backticks because I don't think they're important to what I'm saying. So you disagree with this? Is it a pure black and white thing? I should strive to see that these are always in backticks?
    – CryptoFool
    Commented Apr 5, 2019 at 5:12
  • Real code is a different issue, I feel, because it's often hard to see otherwise where inline code begins and ends. This is not a problem, IMO, when mentioning a class name. Hence why I thought going into this that it's debatable if a class name is code (outside of S.O. anyway).
    – CryptoFool
    Commented Apr 5, 2019 at 5:14
  • ...and, I realize, in saying "always" above, that may be misleading. I mean "only and always, when it's necessary to insure that it's clear what is and isn't code". I don't think we have an issue here. I'm getting the gestalt here, and I tend to be very pragmatic...and I want to follow the rules, not make them.
    – CryptoFool
    Commented Apr 5, 2019 at 5:28
  • 35
    Huh. Maybe I'm a strange person, but to my eyes, the heavily backticked first example you show is nicer on the eyes than either of the subsequent versions. I'd always write things the first way, and find stuff written that way more readable. I'm precisely the the sort of person to "go through other people's posts and apply inline code formatting to every symbol", and I think you're literally the first person I've seen expressing a preference against this; am I the unusual one?
    – Mark Amery
    Commented Apr 5, 2019 at 10:36
  • 9
    @MarkAmery I agree - the more formatted one was easier to read and comprehend IMO. Commented Apr 5, 2019 at 15:01
  • 2
    If I am speed-reading I find your first example the easiest to skim. For the others I have to slow down a bit to see what is being said. That said, your last example may be a teensy bit less distracting when read normally. In general I think I prefer to go with @MarkAmery.
    – hat
    Commented Apr 5, 2019 at 15:54
  • Thanks for all of this. As my question was directed at editing the posts of others, this says to me that I should leave these sorts of things I find in backticks alone. I will do that. I will also think about adding backticks around such symbols, but my main goal was to know how to remove misuse of them from posts.
    – CryptoFool
    Commented Apr 5, 2019 at 16:10
  • I could swear that either Hans Passant or Jon Skeet complained at one point about how difficult it made paragraphs of text to read when inline code formatting was used liberally throughout them, but I can't find a reference either here on MSO or on MSE. It may have been in a comment, which aren't really searchable. Either way, I have to agree. Not semantically, as I said; if the code formatting was better done in the site design, it would probably be fine. But the way it is, I find those big ugly gray blocks to be nothing more than speedbumps to the eyes when used inline.
    – Cody Gray Mod
    Commented Apr 5, 2019 at 17:20
  • 1
    But yeah, larger picture is, perspectives vary on this, and that's why it's probably not good to go imposing your sense of formatting style on other people's posts. I wouldn't want my answers to have overzealous backticks added to them, and Mark wouldn't want his answers to have backticks removed. Both styles are acceptable; that is the point of the answer. It's rather like US English vs. British English spellings. If I say "color", and you say "colour", we're both right. Don't edit to change these.
    – Cody Gray Mod
    Commented Apr 5, 2019 at 17:22
  • @CodyGray could you add special case where a lot of code formatting is essentially required - quoted error messages for languages that use <…> syntax (C++/C#/Java/…) or give alternative guidance for such cases (something like "using List<Foo> is not expected …" renders as "using List is not expected…" with just using quote syntax - so it either need to be marked with ticks around all types or maybe something else) Commented Apr 5, 2019 at 18:38
16

It might also be worth to rephrase your example answer sentence:

You should be passing your someMethod method of your SomeClass class the value "a way cool string literal".

can easily be remodelled to

You can fix your problem by using SomeClassInstance.someMethod("a way cool string literal") instead of what you use now

This is far easier on the eyes as well - most people seeking help on SO are more or less code-fluent and more easily understand this way of writing than broken up code parts in your example answer.

SCNR

2
  • 2
    Sure. That sentence wasn't designed to make sense, but rather just too showcase the backticking of particular kinds of references. I'm mostly talking about correcting misuse of backticks when I'm reviewing proposed edits. I usually won't be looking to rewrite sentences unless they stand out as particularly awkward or confusing.
    – CryptoFool
    Commented Apr 5, 2019 at 6:38
  • I'd argue that the example is a misuse of inline code formatting, it's just that the problem isn't the formatting, but trying to express code in English prose. I guess the lesson is don't focus on the solution, but step back and figure out what the real problem actually is. Commented Apr 5, 2019 at 16:43

You must log in to answer this question.

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