派生类或接口实现的源代码中的 XML 注释
与我之前的问题相关。如果我定义一个接口,我会注释它的成员。然后,我不会评论实现类的实现,除非有原因导致原始评论不再有效。
Resharper 对此表示同意,Visual studio 声称这是一个警告。
重要的是,当您使用继承的注释时,它们会通过智能感知显示,这几乎是我唯一真正关心的问题。
您对此有何看法?
谢谢
Related to my previous question. If I define an interface I'll comment its members. I then don't comment the implementing class's implementation unless there is a reason the original comment is no longer valid.
Resharper is fine with this, Visual studio claims it's a warning.
Importantly the inherited comments are displayed through intellisense when you work with them, which is pretty much my only real concern.
What are your thoughts on this?
Thanks
如果你对这篇内容有疑问,欢迎到本站社区发帖提问 参与讨论,获取更多帮助,或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱,如果其他用户或者作者回复了您的评论,将不能在第一时间通知您!
发布评论
评论(2)
在代码中添加注释始终是一个好习惯。如果组件是私有或内部类,并且它将始终通过具有所有注释的已知接口或抽象类公开,那么您可能只需要注释该类的实现上的特定内容(例如,如果更多比一个人会查看代码,或者如果您碰巧在几年后返回您的代码)。这样就更容易理解代码的作用和原因。如果您在生成项目时启用了生成 XML 文档,Visual Studio 将警告您未记录的成员。
当我启用 XML 文档生成时,我还会收到有关某些类的 Resharper 警告,但 Resharper 仅对具有公共可见性的项目发出警告。
为了缩短文档工作,我建议首先注释公共类和接口(特别是如果您要发布产品库),如果有足够的时间,则注释内部/私有类和接口。如果您决定不对后者进行评论,只需确保您或任何将使用该代码的人能够轻松理解其背后的逻辑及其原因。
Adding comments to your code is always a good practice. If a component is a private or internal class, and it will be always exposed via a known interface or abstract class that has all comments in place, then you may only need to comment specific things on the implementation of that class (for example if more than one person is going to look at the code, or if you happen to return to your code after a few years). That way it will be easier to understand what the code does and why. If you have enabled XML documentation to be generated when you build the project, Visual Studio will warn you for undocumented members.
I am also receiving Resharper warnings on some classes when I enable the XML documentation generation, but Resharper warns only for items with public visibility.
To shorten the documentation work, I'd recommend commenting public classes and interfaces first (especially if you are releasing a product library), and if there is enough time, the internal/private ones. If you decide not to comment the latter, just make sure you or anyone who will be working with the code will easily understand the logic and the reasons behind it.
我刚刚遇到了同样的“问题”,我认为 Visual Studio 正确地报告了代码气味。
如果我理解正确的话,你的问题是,它不是 DRY 拥有什么相当于对您的界面和实现的相同评论。这很有意义——很多时候,尤其是当你进行模拟和测试时,代码将使用接口,而不是实现(当你有接口时)。为什么要重复?
好吧,我敢打赌你的类被标记为
public
。如果是这种情况,外部代码可以在没有接口的情况下使用该类。这些外部用户应该得到一些评论,并且您永远不知道何时有额外的公共方法未在您正在实现的接口列表中捕获。评论一下吧!但是,如果您不想发表这些评论(至少在 VS 2017 中;我意识到您使用的是 2013,我手头没有),您可以标记实现类
内部
并跳过评论。然后你的unDRY评论问题就解决了。
I just ran into the same "issue", and I think Visual Studio is properly reporting a code smell.
Your issue, if I understand correctly, is that it isn't DRY to have what amount to the same comments on your interface and on your implementation. That makes a lot of sense -- much of the time, especially when you're mocking and testing, code is going to use the interface, not the implementation, when you have one. Why duplicate?
Well, I bet your class is marked
public
. If that's the case, the class CAN be used without the interface by outside code. Those external users deserve some comments, and you never know when you have extra public methods that aren't captured in the list of interfaces you're implementing. Comment it up!If you don't want to make these comments, however (at least in VS 2017; I realize you were using 2013, which I don't have handy), you can mark the implementing class
internal
and skip the comments.And then your unDRY comment problem is solved.