Best practice for denoting identifiers and keywords in plain text comments

BenevolentDeity 0
Viewed 34

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>.
comments variables c++
2 Answers

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.

Piotr Cukier0

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.

JustLearning0
Related