I realize this is subjective, but I would like to know if there is a preferred way to denote keywords and the names of variables, functions, macros, etc. when mentioning them in plain text comments. As a simple example I have commented about variables x, y, and z using several formats below. Although x, y, and z are pretty obvious in these examples, in the general case other names often aren't and could possibly misconstrued as just words in the sentence, character literals, string literals, HTML, etc.
// Add x and y and assign to z.
// Add 'x' and 'y' and assign to 'z'.
// Add "x" and "y" and assign to "z".
// Add <x> and <y> and assign to <z>.
CodePudding user response:
Personally, I enjoy deoxygen proposed solution:
// Add \p x and \p y and assign to \p z.
Look at deoxygen manual
It is well standarized format of documenting code, therfore i belive, everyone can easily find the meaning of variable denotifier, even if not obvious at first look.
CodePudding user response:
I use single `. All other options I'm aware of (including the ones you cite as examples) have a reserved usage in most languages, and hence not very convenient for referring to general variables in documentation/comments.