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

问题描述 投票:1回答:2

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

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

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

你对此有何看法?

谢谢

visual-studio-2010 xml-comments
2个回答
0
投票

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

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


0
投票

我刚刚遇到了同样的“问题”,我认为Visual Studio正在报告代码异味。

如果我理解正确的话,你的问题就是DRY在你的界面和你的实现上有相同的评论。这很有意义 - 很多时候,特别是当你进行模拟和测试时,代码将使用接口,而不是实现,当你有一个。为何重复?

好吧,我打赌你的班级标记为public。如果是这种情况,可以在没有外部代码的接口的情况下使用类。那些外部用户值得一些评论,你永远不知道什么时候你有额外的公共方法没有在你正在实现的接口列表中捕获。评论吧!

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

然后你的unDRY评论问题就解决了。

© www.soinside.com 2019 - 2024. All rights reserved.