用XML注释记录C#代码的最佳实践是什么?
-
01-10-2019 - |
题
我正在浏览一些我刚刚编写的新代码,并在我的课程和方法中添加了NDOC Sytle评论。我希望生成一个很好的MSDN样式文档以供参考。
通常,在为班级和方法编写评论时,有什么好的准则? NDOC评论应该怎么说?他们不应该说什么?
我发现自己看着.NET框架的评论说了什么,但这很快就变老了。如果我可以有一些好的指导自己的规则,那么我可以更快地完成文档。
解决方案
在用于构建API文档的评论中,您应该:
解释该方法或属性的作用,为什么根本存在,并解释您代码中普通消费者不认为的任何域概念。
列出您的参数的所有先决条件(不能为null,必须在一定范围内等)。
列出任何可能影响呼叫者处理退货值的后条件。
列出该方法可能会抛出的任何例外(在什么情况下)。
如果存在类似的方法,请解释它们之间的差异。
引起注意任何意外的事情(例如修改全球状态)。
如果有的话,列举任何副作用。
其他提示
如果您最终得到不会增加任何价值的评论,那么它们只是浪费。
例如
/// <summary>
/// Gets manager approval for an action
/// </summary>
/// <param name="action">An action object to get approval for</param>
public void GetManagerApprovalFor(Action action)
...您绝对没有任何价值,只是添加了更多代码以维护。
这些多余的评论常常会散布代码。
Stylecop 提供代码的提示 和 评论风格。它给出的建议符合MSDN文档样式。
至于评论的内容,它应该为您的代码提供足够的信息,以了解期望什么样的行为。它还应该回答用户可能遇到的潜在问题。因此,尝试将您的代码用作对代码一无所知的人,甚至更好,请其他人这样做。
对于属性,您的评论应指示是否仅读取属性,仅写或读写。如果您查看所有官方MS文档,属性文档注释始终以“ get ...”,“ get or sets ...”开始,并且(很少,避免通常仅写属性)“设置...”
不要忘记有效的XML是什么。例如:
/// <Summary>
/// Triggers an event if number of users > 1000
/// </Summary>
(错误:无效XML)。
我写的u003Csummary>评论以包括我想知道的信息是我是一个呼叫该功能(或实例化该类)的信息。
我写的u003Cremarks>评论以包括我想知道的信息,即我是否负责调试或增强该功能或类。注意:这并不能取代对良好的内联评论的需求。但是有时对功能/类内部工作的一般概述非常有帮助。
关于评论的一件事是更新它们。太多的人更改功能,然后不要更改评论以反映变化。