Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

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!

like image 293
Alix Avatar asked Jun 07 '10 12:06

Alix


1 Answers

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

like image 160
b.roth Avatar answered Nov 15 '22 07:11

b.roth