.net – 方法摘要XML注释的良好实践

在我看来,你是正确的< summary>可能是您最常使用的标记,用于解释您的方法究竟要做什么.但是,如果您的方法具有良好,有用的名称,那么期望大多数开发人员将使用它来对该方法的行为方式做出一些假设.例如,他们假设调用“GetName”可能没有副作用,并返回实例的名称,无论评论说什么.

考虑到这一点,我倾向于将我的评论集中在我所知道的任何“问题”上,而不是写一些我知道的“问题”,知道如果有人使用我的代码,并且它不按照他们的方式工作认为它应该,他们要做的第一件事是看文件,希望得到一些指导.以下是我如何使用各种标签的几个例子.

>< returns> – 指示返回值可以为null.描述返回null与string.Empty之间的语义差异
><备注> – 非常适合解释“陷阱”,例如“读者必须处于就绪状态,光标位于正确的位置才能开始阅读.调用者负责在此方法完成后关闭阅读器.”我经常根据需要添加这些注释,在使用API??半小时之后,才会发现一些不明显的愚蠢细节.
>< example> – 好的API应该易于使用,但有时你无法帮助它.这非常适合提供有关如何使用该方法的指导(尽管您不能保证它将如何使用).见下面的例子.

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

我相信还有数以百计的其他例子我可以梦想,但我希望这有助于让你指出正确的方向！