39

I'm talking about things like "you can do that by taking your usersArray and mapping it to each user's name", essentially incorporating part of the inline code into the natural flow of the sentence where it makes sense, in order to tell the reader right away while they are reading the sentence that there are corresponding keywords/methods/etc. that they can use to do these things.

I use that quite frequently as I believe it's concise, but easily readable, and still conveys a lot of meaning this way (as opposed to "you can do that by taking your usersArray array and using the map method to map it to each user's name property").

To elaborate further: If I assume the reader knows that mapping can be done with the map method, I wouldn't code-format it anyway. The way I used it so far was to turn the attention towards the fact that there is actually a method called map that can be used to map stuff. Another example would be something like "You have to await your promise" as opposed to "You have to await your promise using the await keyword". In my eyes the latter is just... awkward, and I find the former much easier to read. Things like "mapping" where only part of the word is the actual code are just the logical extension of that.

Then, today I saw an answer that got edited as follows: It originally said "Make identity_t::operator[] constant." and was changed to "Make identity_t::operator[] constant.". The answer referred to adding a const qualifier to the operator identity_t::operator[].

I looked at the edit summary, but it said nothing ("deleted 2 characters in body"), so my initial reflex was to roll back the edit, as I felt that it is the opposite of an improvement, but then I hesitated since I thought that the editor must have had a strong enough reason. So I thought, maybe this way of inlining is considered bad style, but I couldn't find any source for or against it and in fact didn't even succeed in finding any information about it because I was unable to figure out how to even search for it correctly. (Does this style have a name?)

So, my questions are: What is the general opinion about this style (positive, neutral or negative) and why, and was the edit warranted and/or would a rollback be warranted?


Clarification: This is not a question about using backticks for emphasis or other things that aren't code, so in my opinion it isn't a duplicate of When should code formatting be used for non-code text?, since this is about "Micro-snippets of code" in a certain sense, which is listed as acceptable use there. But this exact usage is not described (neither positively nor negatively) in the other question and its answers.

I'm sorry for the awkward title. I'm not sure how to best describe this in a short way.

30
  • 54
    Breaking the word "constant" up doesn't make sense to me. The fact that it contains const doesn't seem relevant. The context is that it is being used as a complete word
    – charlietfl
    Commented Dec 3, 2021 at 21:46
  • 30
    const is code. "constant" is a word. Writing "constant" allows us to shorten "make it constant using const" to "make it constant" while still making it obvious that we refer to using the const keyword to achieve making it constant.
    – CherryDT
    Commented Dec 3, 2021 at 21:46
  • 17
    This for example: "you can do that by taking your usersArray and mapping it to each user's name". usersArray is iffy, as, Yes, that's a variable and technically code, it isn't necessary... but not wrong, but "maping" is wrong, as mapping is an action, not code (and breaking a word in half that way is awful)
    – Kevin B
    Commented Dec 3, 2021 at 21:47
  • 7
    map is code though, and I even linked the method in question. it is just overlayed onto the the word "mapping".
    – CherryDT
    Commented Dec 3, 2021 at 21:48
  • 15
    Yes, however, your usage of it is not code, it's concept.
    – Kevin B
    Commented Dec 3, 2021 at 21:48
  • 3
    Hm. I see what you mean, but if I assume the reader knows that mapping can be done with the map method, I wouldn't code-format it anyway. The way I used it so far was to turn the attention towards the fact that there is in fact a method called map that can be used to map stuff. Another example would be something like "You have to await your promise" as opposed to "You have to await your promise using the await keyword". In my eyes the latter is just... awkward and I would see that as unnecessarily noisy. Things like "mapping" are just the logical extension of that.
    – CherryDT
    Commented Dec 3, 2021 at 21:55
  • 3
    @CherryDT I'd argue that your Q is a duplicate of that Q, and the accepted A tells you that it is OK to sometimes use code highlighting as you are, and that you will get disagreement on where the grey fuzzy line is Commented Dec 3, 2021 at 22:05
  • 9
    It’s not a gray area. Parts of words that happen to match code identifiers are not code. Code formatting should be used for code, not to highlight parts of natural language words.
    – yivi
    Commented Dec 3, 2021 at 22:11
  • 27
    Because a word that happens to have the same letters as code arranged in the same order isn't code. even in the case of await
    – Kevin B
    Commented Dec 3, 2021 at 22:13
  • 2
    And wrapping await in an inline codeblock does nothing to help readability, regardless of whether you're saying use await or simply using it as part of an explanation. The sentence itself makes it clear what meaning was meant.
    – Kevin B
    Commented Dec 3, 2021 at 22:19
  • 3
    in-line code ticks should be used in places where it will aid readability. it can also be used generally for any bit of the sentence that is actually code, such as "you should use await". there's no, rule, that states you must always use it for code in sentences, nor one saying you shouldn't, or shouldn't use it more than n times, it's a case-by-case basis. Always approach it from the view of readability. codeblocks are presented in a different font meant to make code easier to read, but it doesn't make sentences easier to read.
    – Kevin B
    Commented Dec 3, 2021 at 22:24
  • 4
    IMO, your example would be far easier to read this way: "You're trying to call a non-const function identity_t::operator[] on a const parameter in const function long hash_identity_t::operator( const identity_t& x ). Make identity_t::operator[] constant.". The code is code formatted, the explanation is not.
    – Kevin B
    Commented Dec 3, 2021 at 22:36
  • 5
    As others have said, there are readability issues, which are notably subjective. In the edited answer you linked in your question, the const keyword had already been explicitly mentioned with code formatting 3 times in the immediately preceding sentence. That, IMO, was more than enough to communicate that the const keyword needed to be used. Putting "constant" in partial code formatting was unnecessary in order to communicate that const should be used and makes the code formatting feel even more overused, although the OP there may have been trying for minor humor.
    – Makyen Mod
    Commented Dec 4, 2021 at 4:27
  • 11
    OTOH, IMO, your short sentence examples using "mapping" have "mapping" as the only place the .map() method name is shown, so code format is not just reasonable, but desirable, particularly in combination with linking it to documentation, in order to be clear that you're talking about the actual .map() method, rather than some possible other metaphorical way of mapping. For these, I'd probably prefer ".map()ing" to be extra explicit, given the single use of map.
    – Makyen Mod
    Commented Dec 4, 2021 at 4:28
  • 12
    Just say "a const" instead of "constant". The latter is awkward and confusing to parse while reading.
    – TylerH
    Commented Dec 6, 2021 at 14:32

4 Answers 4

58

Code blocks mark a language boundary; only use them when your formatting helps to distinguish prose meanings from code meanings.

Partial-word code blocks can be particularly distracting or can impair readability; only use them with well-understood prefixes and suffixes.


The goal here should be to make it clear which words and marks you should read as their English (or other prose language) meaning and which words you should read as their code meaning. In a question about Android Java, this can mark the difference between:

  1. finish your activity
  2. finish your activity
  3. finish your Activity
  4. finish your Activity

And as in Jeanne Dark's linked question When should code formatting be used for non-code text?, we all benefit by sticking to that rule, as opposed to misusing code blocks for emphasis of English words.

As you mention in your question, this can lead to a gray area where the English word and keyword are perfectly identical in spelling and part of speech, like finish (above) or await in JavaScript. Furthermore, many words may be readable as code simply by capitalizing them, which for example makes the difference between Activity and Activity less valuable. This is a matter of readability, and readability is somewhat personal: I'll tend to use capitalized Identifiers and UpperCamelCase in prose, but as soon as I need punctuation(), spaced phrases like do while, or lowerCamelCase I'll use backticks.

Regarding mid-word changes, one nifty thing about English in particular is its flexibility. As an English language user we can use language rules for pluralizing words and "verbing our nouns", or apply English spelling rules to words from other languages. "Futon" is a Japanese borrowing, so it has no natural plural; we pluralize it in English as "futons". "Xerox" and "Kleenex" are brand names, but if you say "Xeroxed" or "Kleenexes", the meaning is clear.

In this sense, borrowing Jeremy Caney's examples:

  • ✔️ DateTimes: You're pluralizing the code noun DateTime, so this makes sense.
  • ✔️ Save()d: You're adjusting the code verb Save to past tense, so this makes sense.
  • ✔️ fastRendering: You're adjusting the code verb fastRender to the present progressive, so this makes sense.
  • ✔️ thenable: You're describing an object you can call then on. This neologism defined in the Promises/A+ specification has become popular enough that it often does not need formatting at all, but I mention it because it follows the same rules and might have warranted this formatting earlier in the days of the Promise specification.
  • mapping: I would use mapping to distinguish from flatMapping, but "mapping" makes enough sense without the formatting that I'd probably skip backticks in most cases. The necessary doubling of "p" makes this especially awkward.
  • awaiting: Same here. In many cases it might not provide value, though a novice would be less likely to ask "how do I await it?" if you say "await the value" instead of "await the value".
  • constant: The "-ant" cannot be understood as a suffix here. (You wouldn't put varant or Intant, would you?) Though you're hoping for the simultaneous reading of "constant" and const, the formatting and dual readings make this harder to treat as a single word than with the prefixes and suffixes used above.
  • variable, application, manual, dictionary, etc.

Note here that a ✔️ is meant to indicate which cases follow the described rule, not that those cases are always helpful or appropriate. Readers might find mid-word formatting to be distracting: unless you have character constraints (as in comments) you might favor one of the alternatives in kaya3's answer.

10
  • 6
    Thank you for the extensive answer. Could you just clarify what you mean by constant being demonstrably wrong by comparing it with Intant? I mean, "constant" is a word (the word const originates from) and "Intant" isn't. Do you mean the issue is that const alone wouldn't be a real English word and that's why it's a problem, so "it should be an asynchronous" function would be bad too? (I do agree that the latter looks awkward because of the "ch" being broken up though.) Or, to use Int, something like "You need an Integer for that".
    – CherryDT
    Commented Dec 4, 2021 at 8:18
  • 15
    @CherryDT "constant" is a word but in order to form it, you have to add "-ant" at the end of "const". This isn't a regular suffix in English. Compare with the examples above: "-s", "-d" (which can also be "-ed" in other situations), "-ing" (well "-<repeat consonant)ing" in this case due to spelling rules). These are regular suffixes that you can add to almost any word to turn it into a related word. By comparison "-ant" is not. Nor is "-iable", "-lication", "-ual", "-ionary".
    – VLAZ
    Commented Dec 4, 2021 at 8:54
  • Another very common example from the Android world is "Intent" (or is it "intent"?). Even an official page spell it in two different ways (I am not sure if the context is different or not): "An intent is an abstract description..." and "An Intent provides a facility..." (my emphasis). Commented Dec 4, 2021 at 12:22
  • 3
    @CherryDT VLAZ has it right; it comes down to standard prefixes and suffixes, which I probably should have mentioned explicitly in the body. I consider these formatting conventions as some of English's fun undocumented rules, like those regarding expletive infixation or adjective order. FWIW, I mean to describe what I believe are the rules here, not to declare them myself or empower grammar police (or constables). Commented Dec 4, 2021 at 16:34
  • 10
    I'm not a fan of mapping... the small space reads as "map ping" to me.
    – Shadow
    Commented Dec 6, 2021 at 1:48
  • 5
    "you wouldn't put varant or Intant, would you?" Well, no, but that's not how constant is being used. Equivalents would be variant and integer (but the practice is still wrong overall).
    – TylerH
    Commented Dec 6, 2021 at 14:34
  • @VLAZ Your comment seems like it is introducing a little bit of confusion. "Const" isn't a word in English... so it's not really correct to say "you add 'ant' to the end of 'const' to form constant"... you don't do that, you just... write the whole word, which is 'constant'.
    – TylerH
    Commented Dec 6, 2021 at 14:39
  • @Tyler: Right, I am here establishing the rule that we should honor modification but not coincidence nor expansion of abbreviations. The dismissal of varant is meant to demonstrate the inapplicability of -ant as a suffix, not to suggest that the OP would have used that in earnest. Commented Dec 6, 2021 at 15:48
  • 2
    @JeffBowman I don't think anyone was under the impression OP was using "ant" as a fixed suffix for data type keywords. It seems pretty obvious const is followed by "ant" because the word in English is "constant". In other words, OP is just... finishing the word.
    – TylerH
    Commented Dec 6, 2021 at 15:52
  • 2
    @Tyler I believe that despite the author's intention, it reads initially as though they were using "-ant" as a suffix: their intended word expansion of const doesn't land because of the language change implied by the formatting, which would lead the reader to understand this as a morphological boundary instead. Based on your other comments, I think we largely agree here: I'm using the phrasing to demonstrate the applicability of my rule, not to misinterpret theirs. Commented Dec 6, 2021 at 16:02
53

I think occasionally it is OK, but most of the time a different phrasing only costs one extra word, and adds enough extra clarity and readability that the trade-off is worth it:

  • "Use DateTimes in these instances" → "Use DateTime objects in these cases", unless "instances" is used in its technical meaning
  • "You Save()d the value" → "You called Save() on the value"
  • "fastRendering" → "calling fastRender"

The term "thenable" has become accepted now, so you can just write "thenable" without any code formatting; but hypothetically if this term were not widely understood then I would favour writing "thenable" without code formatting but a link to a relevant explainer. Or if hypothetically the term were so non-standard that there was no good explainer to link to, then perhaps it would not be best to coin the term yourself:

  • "The object is thenable" → "The object supports then"
  • "It accepts a thenable" → "It accepts an object supporting then"

So let's talk about "make it a constant":

  • If the reader knows what the const keyword means and what it does, then "make it a const" gets the point across perfectly well.
  • So the extra "-ant" suffix is surely aimed at readers who don't already know enough about const. I argue that "make it a constant" is not sufficient to explain to those readers, but just with a few extra words, "make it a constant using the const keyword" explains what const means and how to use it.
  • Or, write "make it a const" with a link to a relevant explainer.

The same applies for "asynchronous", "integer", "dictionary" and so on: if you think the keyword or type name isn't enough, then either write a proper explanation or link to one.

This particularly matters when inline code is formatted with padding. On Stack Overflow, that padding is about as wide as a space character in regular text, so "constant" takes an extra moment to read because you have to notice that the "space" between the 't' and the 'a' is not meant to separate two words. Compare the screenshots below: on the right, I manually edited the style to remove the horizontal padding.

enter image description here

All of that said, I don't "frown upon" this practice; I prefer to avoid it myself and I encourage others to avoid it (for the reasons outlined above), but I would never judge somebody negatively for doing it, especially in comments as opposed to answers.

6
  • I would rather describe this as "like Jeff's, but better/more accurate", rather than "different"; you both largely agree on the main points.
    – TylerH
    Commented Dec 6, 2021 at 14:39
  • 4
    Indeed. We're not writing for fourth-graders here, IMO Stack Overflow content should be written like you would write a paper. The constant highlighting is nothing more than hindering the reader with constant brain-hiccups, highlighting words within words is doubling down on the hindering, what are you trying to achieve by doing that I wonder... I think people take programming optimisation and start to apply it to text.
    – Gimby
    Commented Dec 6, 2021 at 15:05
  • You can even keep it more concise than the original, saying "make it const" instead of your suggestion of "make it a const". That sounds grammatical to me, because const is something variables or methods can be. (IMO, the edits CherryDT described were highly sub-optimal choices for fixing the readability problem, though, as they removed mention of the appropriate keyword or function names.) Commented Dec 6, 2021 at 16:34
  • I'm not sure our opinions actually differ here. I say "here are the undocumented observed rules about where you can break a word boundary" and yours seems to be "here are concise alternatives so you don't have to break a word boundary". They seem complementary to me, your text just weighs the readability cost a little heavier than mine does. Commented Dec 6, 2021 at 16:53
  • @JeffBowman That's fair. I said that my opinion is different mainly because your use of green checkmarks makes it look like you're endorsing some things which I am advising against. If you just meant to describe what seems to be accepted by the community then perhaps I misunderstood.
    – kaya3
    Commented Dec 6, 2021 at 17:25
  • 1
    @kaya3 See my edits just now, including to the above-the-line summary: My checkmarks are more about demonstrating the rule than fully endorsing the behavior. I've likewise linked to your answer for alternatives. Commented Dec 6, 2021 at 18:31
12

Yes, when it impairs readability.

"constant" and similar constructs impair readability because they force your brain to make multiple passes over the word to figure out its meaning. Your brain first reads and parses the "const" part, then has to context switch to read and parse the differently-formatted "ant" part. Then it has to build a decision tree with the various possibilities it's determined, and traverse that tree using the context information present to weight the leaves and ultimately decide on an interpretation. Because "const" and "ant" are in two different contexts, the tree is deeper and wider than if it were simply reading a single word in a single context - in particular, there are far more potential paths for mistakes (e.g. is this intended to be "const" + [omitted space] + "ant"?) In short, your brain has to do a lot of work to get from "constant" to "constant", even if you don't realise it.

When you write something, it is for others to consume, and you should focus on making it easy for them to consume. Arbitrarily syntax-highlighting words in paragraphs makes consumption unnecessarily difficult; arbitrarily syntax-highlighting parts of words is honestly just obnoxious. It doesn't have any positive effects, only negative ones, so in general... just don't do this.

But what if you really have a valid scenario to use this? Thankfully, English already has a way to explicitly represent a context switch: punctuation. I prefer to use the humble hyphen, so would write "const-ant", which tells your brain that the -ant is intentional, not a mistake. This means that while the decision tree has the same number of branches and leaves as with "constant", far less weight is placed on the "possible mistake" routes, which means your brain is able to arrive at the correct answer of "constant" more quickly.

Be kind to your brain.

0

This is obviously a question of style, and like all style questions, it is largely a matter of opinion, and thus endlessly debatable.

There's at least one additional factor which plays pretty heavily into this particular style question, though, and that is that computer geeks purely love font changes. (I say this with no animosity towards computer geeks: I myself am a reasonably hardcore computer geek, and I purely love font changes, too.)

More normal people, on the other hand, tend to view excessive font changes as distracting. There's no hard-and-fast rule about what percentage of font change is acceptable versus distracting, but we can certainly say that the number of changes which a computer geek thinks is perfectly dandy is likely to be well into the territory that a more normal reader finds distracting.

So the reasonably obvious conclusion is: don't overuse your ability to render keywords and other computer geeky identifiers in monospace/typewriter/<pre> font. Make sure it's really necessary in order to eliminate ambiguity or aid comprehension; make sure you're not just showing off how much fun it is to use markdown syntax as you're texting.


[almost a separate answer]

There's also a linguistic component to this. Most human languages have various kinds of markers for various parts of speech, although it's a defining characteristic of a language whether it does this a lot or a little. For example, in German, all nouns are capitalized, while in English, only proper nouns are capitalized.

There's also a typographical convention, at least in English but I presume in other languages, of rendering foreign words in italics. So people will write things like "I presume you're au courant on these stylistic issues?".

I believe that the impetus for rendering computer keywords and other identifiers in monospace font stems from an analogous urge. An identifier in a computer language is significantly distinct from an ordinary noun, so it seems like maybe it ought to be distinguished in some special way. Also, whatever computer language we're taking about is not English, so it might be useful to distinguish its syntax specially. So, logically, the proclivity to render every single keyword and identifier in a sentence as monocase is, I believe, defensible — but still, it can be distracting when overdone.

And constant, I'd say, is right out.

5
  • 1
    Aren't developers by definition computer geeks?
    – CherryDT
    Commented Dec 6, 2021 at 16:12
  • 1
    @CherryDT Certainly not. There's a huge range. Some computer geeks are geeky even by computer geek standards. And computer protramming (and related fields like web development) are now mainstream, so there are plenty of people — including I suspect a large fraction of the people asking questions on Stack Overflow — who are not (and would rather not be called) computer geeks at all. Commented Dec 6, 2021 at 16:14
  • 1
    I guess what I'm trying to say is that the definition of "computer geek" has become very ambiguous by now, I feel like people in the more technical spectrum have a different definition (that often doesn't include themselves) than people from different fields - which is why I think many non-developers would call developers computer geeks, while - as you just proved - many developers would not.
    – CherryDT
    Commented Dec 6, 2021 at 16:19
  • 1
    @CherryDT people in the more technical spectrum Now that is a lovely, lovely coinage. :-) My point was just that if you're writing a Stack Overflow answer, you probably shouldn't assume that the OP is as much of a computer geek (however you define the term) as you are. Commented Dec 6, 2021 at 16:23
  • I am not convinced that the use of inline monospace is purely stylistic. The use of punctuation is also different from English prose, such that even ignoring indentation concerns [a.b(), c[d]] and [a.b(), c[d]] are less readable than [a.b(), c[d]]. The utility of monospace extends for consistency to English-like words (for, await) for which italics would be similarly useful. Commented Dec 6, 2021 at 21:42

You must log in to answer this question.

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