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

我最近在程序的顶部使用了方法摘要 XML Comments,并且想知道是否存在与此相关的任何逻辑或良好实践.

我从未在评论中添加任何内容,因为我将方法的描述放在摘要标记中.什么属于摘要,什么属于备注？

我很少在返回标记中放置任何内容,因为它似乎是多余的,因为我通常会解释摘要中返回的内容.我应该简单地保留返回标记中返回的对象类型吗？

任何人都可以建议这些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>

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