Documentation style: how do you differentiate variable names from the rest of the text within a comm
- by Alix
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!
