我应该如何记录继承的成员? [英] How should I document a inherited members?

问题描述

考虑到我有一个复杂的类结构，其中许多元素是从其他元素继承的.我可能在接口中定义了方法GetStuff(string stuffName, int count)，该方法由其他接口继承，然后由抽象类抽象地实现，然后在具体类中显式实现，等等.

Consider that I have a complex class structure where many elements inherit from other elements. I may have a method GetStuff(string stuffName, int count) defined in an interface, which is inherited by other interface, which is then implemented abstractly by an abstract class, which is then implement explicit in a concrete class etc. etc...

在使用XML注释记录我的代码时，我该如何处理诸如GetStuff()之类的继承成员，这些注释将与Doxygen或Sandcastle之类的工具一起使用?仅在每个级别上复制并粘贴相同的描述似乎是错误的.我应该在界面级别还是在具体的课程级别考虑不同的受众?例如，接口上的GetStuff()文档可能考虑实现该接口的人员，而具体级别的文档可能考虑使用该类的人员?

How should I handle inherited members such as GetStuff() when documenting my code with XML comments which will be used with a tool such as Doxygen or Sandcastle? It seems wrong to just copy and paste the same description at each level. Should I be considering a different audience at the interface level vs the concrete class level? For example the documentation for GetStuff() at the interface may consider people implementing the interface, whereas the documentation at the concrete level may instead consider people who will be using the class?

推荐答案

• 根据其代码约定记录接口方法.请勿仅针对其语义目的(即其应做的事情)评论其实现，不怎么样.本文档的读者是您的实现者和用户的 :该方法既实现又被调用.

  • Document the interface method according to its code contract. Do not comment on its implementation, only on its semantic purpose, i.e. what it’s supposed to do, not how. The audience for this documentation is both your implementors and your users: the method will both be implemented as well as called.

    简单地说出抽象方法的文档即可，它说它实现了接口方法并链接到该接口方法.没什么好说的了，重复评论违反了DRY(不要重复自己)的原则:您必须记住在两个地方都进行任何更改. (当然，对于没有实现接口方法的抽象方法，请以与记录接口方法相同的方式对其进行记录.)

    Document the abstract method simply by saying that it implements the interface method and linking to it. There is nothing extra to be said about it, and duplicating the comment violates the DRY (Don’t Repeat Yourself) principle: you would have to remember to make any change to it in both places. (Of course, in the case of an abstract method that doesn’t implement an interface method, document it in the same way that you would document an interface method.)

    记录具体实现，方法是说它实现了接口方法和/或覆盖了抽象成员. (可选)添加有关其实现的信息(如果它与调用方相关)-例如，其性能特征或可能抛出的情况等.

    Document the concrete implementation by saying that it implements the interface method and/or that it overrides the abstract member. Optionally add information about its implementation if it is relevant to the caller — for example, its performance characteristics, or situations in which it might throw, etc.

    这篇关于我应该如何记录继承的成员?的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！