复制关于接口实现/重写文档的好坏?


20

所以我们有一个像这样的界面

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

最近,我们播放了一个文档故事,涉及生成并确保像上面那样有大量XML文档。但是,这导致了很多重复的文档。示例实现:

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

如您所见,方法文档是界面的直接内容。

最大的问题是,这是一件坏事吗?由于重复,我的直觉告诉我是,但是又可能不是吗?

另外,我们还有其他类似的override功能和virtual功能重复的文档。

这不好吗?应该避免吗?完全值得吗?


如果使用Resharper,则只能在实现中更改注释,然后使用“上拉成员”来更新界面。
vortexwolf 2013年

我这样做是因为,也许是因为我不太擅长使用外部工具,而是更喜欢去浏览接口的头文件以查看我可以对特定类型的事情进行处理(这是针对C和C ++的,源文件标题的概念)。它的确有些重复,但是我尝试寻找机会添加与覆盖该方法的具体类有关的更具体的细节,例如,我喜欢它,并且有一个强迫症,如果我不这样做,我会忽略一些重要的东西请参阅头文件中每个功能的注释。

我实际上使用了Doxygen注释和标签,但实际上我在编码过程中并不怎么看文档。我更喜欢只导航到头文件,看看我能做些什么。可能只是一只老狗很难养成新习惯和新工具的情况。

Answers:


9

通常,只有在需要提及实现的特定内容时才将新文档添加到实现的方法中。

在javadoc中,您可以链接到其他方法,这将允许您只在实现中创建到接口中方法文档的链接。我认为这是应该在.Net中完成的方式(基于我阅读的在线文档,而不是我自己的经验):

/// <summary>
/// Interface for classes capable of creating foos
/// </summary>
public interface ICreatesFoo
{
  /// <summary>
  /// Creates foos
  /// </summary>
  void Create(Foo foo);
  /// <summary>
  /// Does Bar stuff
  /// </summary>
  void Bar();
}

/// <summary>
/// A Foo Creator which is fast
/// </summary>
public class FastFooCreator : ICreatesFoo
{
  /// <summary>
  /// <see cref="ICreatesFoo.Create(Foo)"/>
  /// </summary>
  public void Create(Foo foo)
  {
    //insert code here
  }
  /// <summary>
  /// <see cref="ICreatesFoo.Bar()"/>
  /// Also Note: Implementation of Bar() in FastFooCreator
  /// requires a minimum of 512 MB RAM to Bar the Foo. 
  /// </summary>
  public void Bar()
  {
    //code here
  }
}

<see/>元素的文档:http : //msdn.microsoft.com/zh-cn/library/acd0tfbe.aspx


如何在继承的类中覆盖XML文档?假设我是的子类,Collection<T>并且想覆盖其Count属性XML文档。
2015年
By using our site, you acknowledge that you have read and understand our Cookie Policy and Privacy Policy.
Licensed under cc by-sa 3.0 with attribution required.