Geek Answers Handbook

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

This is a rather redundant and uninteresting question, I am afraid, but I am always surprised at this. When you comment on code with inline comments (as opposed to comments that appear in the generated documentation) and the variable name appears in the comments, how do you distinguish it from plain text? For instance:.

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

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

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

As well as:

// Try to parse variable type.

(I don’t think the latter is very useful, it’s a bit confusing, you might think that a “variable” is an adjective)

- ? , - ; , , , , .

( , , , : @code, <code> </code> , ..)

!

+5
3

, , .

+2

99.9% PHP, :

// Try to parse $type.

, ( , , , , ;))

// Try to parse 'type'.
+2

, , , , .

, , , - code + comment = context for understanding.

, - : , , , .

+2

More articles:


All Articles