¿Duplicar documentación sobre implementaciones de interfaz / anulaciones buenas o malas?

20

Entonces tenemos una interfaz como esta

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

Recientemente, reprodujimos una historia de documentación que implicaba generar y garantizar que haya mucha documentación XML como la anterior. Sin embargo, esto causó mucha duplicación de documentación. Implementación de ejemplo:

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

Como puede ver, la documentación del método es una copia directa de la interfaz.

La gran pregunta es, ¿es esto algo malo? Mi instinto me dice que sí debido a la duplicación, pero de nuevo tal vez no.

Además, tenemos otra duplicación de documentación similar con overridefunciones y virtualfunciones.

¿Es esto malo y debe evitarse o no? ¿Vale la pena incluso?

c# documentation xml documentation-generation Earlz
fuente
Si usa Resharper, puede cambiar los comentarios solo en la implementación y luego actualizar la interfaz mediante el uso de "Pull members up".
vortexwolf
Hago esto, pero tal vez porque no soy tan bueno usando herramientas externas y prefiero ir al archivo de encabezado de una interfaz para ver qué puedo hacer con un tipo particular de cosas (esto es para C y C ++ que separan la noción de encabezado del archivo fuente). Se vuelve un poco repetitivo, pero trato de encontrar oportunidades para agregar detalles más específicos relacionados con la clase concreta que anula los métodos, por ejemplo, me gusta y tengo un problema de TOC donde siento que omití algo importante si no lo hago. ver comentarios para cada función en un archivo de encabezado.
De hecho, uso los comentarios y etiquetas de Doxygen, pero en realidad no miro los documentos tanto en el proceso de codificación. Prefiero navegar al archivo de encabezado y ver qué puedo hacer con algo. Podría ser el caso de un perro viejo que tiene dificultades para aprender nuevos hábitos y herramientas.

Respuestas:

9

En general, solo agregaría nueva documentación a los métodos de implementación si hay algo específico sobre esa implementación que deba mencionarse.

En javadoc puede vincular a otros métodos, lo que le permitiría crear un enlace en la implementación a la documentación del método en la interfaz. Creo que así es como se debe hacer en .Net (basado en mi lectura de la documentación en línea, no en mi propia experiencia):

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

La documentación para el <see/>elemento: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

FrustratedWithFormsDesigner
fuente
¿Qué tal anular los documentos XML en una clase heredada? Digamos que hago una subclase de Collection<T>y quiero anular sus Countdocumentos XML de propiedad.
Shimmy