.net - 方法摘要XML注释的良好做法

Question

最近，我一直在过程的顶部使用方法摘要XML Comments，并且想知道是否与此相关的任何逻辑或良好实践。

我从来没有在备注中添加任何内容，因为我将方法的描述放在了摘要标签中。摘要中包含哪些内容，备注中包含哪些内容？

我很少在returns标记中放入任何内容，因为在我通常要解释摘要中返回的内容时，这似乎是多余的。我应该只在返回标签中保留返回的对象类型吗？

任何人都可以对这些XML注释提出一种良好，逻辑或常用的建议，这对团队中的其他程序员有利，而又不需要多次显示相同的信息吗？

Answer 1

在我看来，您正确的认为

可能是您最常使用的标签，用于解释您的方法的确切含义。但是，如果您的方法具有好的名称，有用的名称，那么可以期望大多数开发人员会使用该名称对方法的行为进行一些假设。例如，他们假设调用“GetName”可能没有副作用，并且不管实例怎么说，都返回实例的名称。

考虑到这一点，我倾向于将注释集中在我所知道的任何“陷阱”上，而不是写关于该方法应该做什么的段落，因为我知道如果有人使用了我的代码，并且这种方式不符合他们的工作方式认为应该这样做，他们要做的第一件事就是查看文档，以期获得一些指导。以下只是一些有关如何使用各种标签的示例。

<returns>-指示返回值可以为null。描述返回的null与string.Empty

之间的语义差异

<remarks>-非常适合解释“陷阱”，例如“阅读器必须处于就绪状态，并且光标位于正确的位置才能开始阅读。在此方法完成后，调用方负责关闭阅读器。”我通常会在API忙了半个小时之后根据需要添加这些注释，然后才意识到一些不明显的愚蠢细节。

<example>-好的API应该易于使用，但有时您无能为力。这对于提供有关如何使用该方法的指导非常有用(尽管您不能保证一定会使用该方法)。请参见下面的示例。

<example>
var token = m_caller.GetAuthToken();
var result = m_caller.Call(method, token);
</example>

我敢肯定，还有数百个我可以梦想的例子，但是我希望这可以帮助您指出正确的方向!