文档样式:如何在注释中区分变量名称与文本的其余部分？

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,<code> </ code>等)

谢谢!

Answer 1

您提到的任何这些样式，只要您的文档之间保持一致性即可。