文档样式 : how do you differentiate variable names from the rest of the text within a comment?

Question

关闭。这个问题是opinion-based .它目前不接受答案。












想改善这个问题吗？更新问题，以便可以通过 editing this post 用事实和引文回答问题.

3年前关闭。




Improve this question




恐怕这是一个非常多余且无趣的问题，但我总是对此感到疑惑。当您使用内联注释(而不是将出现在生成的文档中的注释)注释代码并且变量名称出现在注释中时，您如何将其与普通文本区分开来？例如。:

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

在注释中，“type”是变量的名称。您是否以任何方式标记它以表示它是一个符号而不仅仅是评论文本的一部分？我见过这样的事情:

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

并且:

// Try to parse variable type.

(我不认为最后一个很有帮助；有点困惑；你可能认为“变量”是形容词)

你有什么偏好吗？我发现我需要使用某种标记；否则，注释有时会模棱两可，或者至少当您意识到注释中的特定单词实际上是变量的名称时，会迫使您重新阅读它们。

(在将出现在文档中的注释中，我为生成器使用了适当的标签，当然:@code、 等)

谢谢!

Answer 1

我 99.9% 的时间都在做 PHP，但不存在这个问题:

// Try to parse $type.

但是当我用其他语言做一些事情时，我喜欢单引号(但我认为你使用什么不是很重要，但你每次都应该使用相同的，而不是在每个评论中都改变它;)):

// Try to parse 'type'.