Duplicating documentation on interface implementations/overrides good or bad?

Question

So we have an interface like so

/// <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();
}

Recently, we played a documentation story which involved generating and ensuring that there is plenty of XML documentation like above. This caused a lot of duplication of documentation though. Example implementation:

/// <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
  }
}

As you can see the method documentation is a straight rip from the interface.

The big question is, is this a bad thing? My gut tells me yes because of duplication, but then again maybe not?

Also, we have other similar documentation duplication with override functions and virtual functions.

Is this bad and should be avoided, or not? Is it at all worthwhile even?

If you use Resharper, you can change comments only in the implementation and then update the interface by using "Pull members up". — vortexwolf, Apr 04 '13 at 16:15
I do this but maybe because I'm not so good at using external tools and prefer to just go navigate to the header file of an interface to see what I can do with a particular type of thing (this is for C and C++ which separate the notion of header from source file). It does get a bit repetitive but I try to find opportunities to add more specific details relating to the concrete class overriding the methods, e.g. I like it and I have an OCD thing going where I feel like I omitted something important if I don't see comments for every function in a header file. — , Dec 20 '17 at 07:15
I actually use Doxygen comments and tags but I actually don't look at the docs so much in the process of coding. I prefer to just navigate to the header file and see what I can do with something. Might just be a case of an old dog having a hard time picking up new habits and tools. — , Dec 20 '17 at 07:19
This is an old question, but since it's high in the google search results: The modern way to avoid duplication is to use `/// `. This allows you to inherit the documentation of a base class or interface. I don't have enough reputation here to post this as an answer though. — D-Inventor, Aug 22 '21 at 11:57

FrustratedWithFormsDesigner · Answer 1 · 2013-04-04T16:15:25.780

In general, I'd only add new documentation to the implementation's methods if there's something specific about that implementation that needs to be mentioned.

In javadoc you can link to other methods, which would allow you to just create a link in the implementation to the method documentation in the interface. I think this is how it's supposed to be done in .Net (based on my reading the online documentation, not my own experience):

/// <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
  }
}

The documentation for the <see/> element: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

How about overriding the XML docs in an inherited class? Say I make a sub-class of `Collection` and want to override its `Count` property XML docs. — Shimmy Weitzhandler, May 04 '15 at 18:55

Duplicating documentation on interface implementations/overrides good or bad?

1 Answers1