I'm talking about things like "you can do that by taking your usersArray
and map
ping 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 "map
ping" 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[]
const
ant." 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.
const
doesn't seem relevant. The context is that it is being used as a complete wordconst
is code. "constant" is a word. Writing "const
ant" allows us to shorten "make it constant usingconst
" to "make itconst
ant" while still making it obvious that we refer to using theconst
keyword to achieve making it constant.usersArray
andmap
ping 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 "map
ing" is wrong, as mapping is an action, not code (and breaking a word in half that way is awful)map
is code though, and I even linked the method in question. it is just overlayed onto the the word "mapping".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 calledmap
that can be used to map stuff. Another example would be something like "You have toawait
your promise" as opposed to "You have to await your promise using theawait
keyword". In my eyes the latter is just... awkward and I would see that as unnecessarily noisy. Things like "map
ping" are just the logical extension of that.app
ens to have the samelet
ters as codearr
anged in the sameorder
isn't code. even in the case of awaitawait
". 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.identity_t::operator[]
on a const parameter in const functionlong hash_identity_t::operator( const identity_t& x )
. Makeidentity_t::operator[]
constant.". The code is code formatted, the explanation is not.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 theconst
keyword needed to be used. Putting "const
ant" in partial code formatting was unnecessary in order to communicate thatconst
should be used and makes the code formatting feel even more overused, although the OP there may have been trying for minor humor.map
ping" 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 ofmap
.const
" instead of "const
ant". The latter is awkward and confusing to parse while reading.