Documentation style: how do you differentiate variable names from the rest of the text within a comment?

Question

Hi,

This is a quite superfluous and uninteresting question, I'm afraid, but I always wonder about this. When you're commenting code with inline comments (as opposed to comments that will appear in the generated documentation) and the name of a variable appears in the comment, how do you differentiate it from normal text? E.g.:

// Try to parse type.
parsedType = tryParse(type);

In the comment, "type" is the name of the variable. Do you mark it in any way to signify that it's a symbol and not just part of the comment's text? I've seen things like this:

// Try to parse "type".
// Try to parse 'type'.
// Try to parse *type*.
// Try to parse <type>.
// Try to parse [type].

And also:

// Try to parse variable type.

(I don't think the last one is very helpful; it's a bit confusing; you could think "variable" is an adjective there)

Do you have any preference? I find that I need to use some kind of marker; otherwise the comments are sometimes ambiguous, or at least force you to reread them when you realise a particular word in the comment was actually the name of a variable.

(In comments that will appear in the documentation I use the appropriate tags for the generator, of course: @code, <code></code>, etc)

Thanks!

Answer 1

ANY of these styles that you mentioned, as long as there is consistency across your documentation.

Answer 2

99.9% of my time i'm doing PHP, where this problem doen't exist:

// Try to parse $type.

but when i do some stuff in other languages, i like single quotation marks (but i think it isn't very important what you use, but you should use the same every time, not changing it in every comment ;) ):

// Try to parse 'type'.

Answer 3

In the example provided, the comment combined with the line of code that is being commented provides all of the context required to understanding what was written.

In fact, even when dealing with a comment that is meant to explain a block of code, it is usually not going to be an issue - code + comment = context for understanding.

That all said, and as someone else mentioned: so long as you're consistent, any of the methods you picked works.