Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

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?

share|improve this question
    
If you use Resharper, you can change comments only in the implementation and then update the interface by using "Pull members up". –  vorrtex Apr 4 '13 at 16:15
add comment

1 Answer

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

share|improve this answer
add comment

Your Answer

 
discard

By posting your answer, you agree to the privacy policy and terms of service.

Not the answer you're looking for? Browse other questions tagged or ask your own question.