派生类或接口实现的源代码中的XML注释

时间:2011-07-05 10:28:05

标签: visual-studio-2010 xml-comments

与我之前的问题相关。如果我定义一个接口,我会评论其成员。然后我不评论实现类的实现,除非原始注释不再有效。

Resharper对此很好,Visual studio声称这是一个警告。

重要的是,当您使用intellisense时,继承的注释会通过intellisense显示,这是我唯一真正关心的问题。

您对此有何看法?

由于

2 个答案:

答案 0 :(得分:0)

为代码添加注释始终是一种好习惯。如果组件是私有或内部类,并且它将始终通过已知的接口或具有所有注释的抽象类公开,那么您可能只需要对该类的实现进行特定的评论(例如,如果有的话)比一个人要查看代码,或者几年后你碰巧回到代码中)。这样就可以更容易理解代码的作用和原因。如果已在生成项目时启用了XML文档,则Visual Studio将警告您未记录的成员。

当我启用XML文档生成时,我也在某些类上收到Resharper警告,但Resharper仅警告具有公共可见性的项目。 为了缩短文档工作,我建议首先评论公共类和接口(特别是如果你要发布产品库),如果有足够的时间,内部/私有的。如果您决定不对后者发表评论,请确保您或将使用该代码的任何人都能轻松理解其背后的逻辑和原因。

答案 1 :(得分:0)

我只是遇到了相同的“问题”,我认为Visual Studio正确地报告了代码异味。

如果我的理解正确,那么您的问题是,DRY在您的界面和实现上有多少相同的注释不等于什么。这很有意义-在很多时候,尤其是当您进行模拟和测试时,如果有一个,代码将使用该接口,而不是实现。为什么要重复?

好吧,我敢打赌您的班级被标记为public。在这种情况下, 可以通过外部代码在没有接口的情况下使用该类 。那些外部用户应该得到一些评论,并且您永远不知道什么时候您还有正在实现的接口列表中未捕获到的其他公共方法。发表评论!

但是,如果您不想发表这些评论(至少在VS 2017中;我意识到您使用的是2013,我没有用),您可以标记 internal并跳过评论

然后您的unDRY评论问题得到解决。