¿Duplicar documentación en implementaciones de interfaz / reemplaza bueno o malo?

Navega tus respuestas
14

Así que tenemos una interfaz como tal 

/// <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, jugamos una historia de documentación que involucraba la generación y la garantía de que hay mucha documentación XML como la anterior. Esto causó mucha duplicación de documentación sin embargo. Ejemplo de implementación: 

/// <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 un rasgón directo desde la interfaz.

La gran pregunta es, ¿es esto algo malo? Mi instinto me dice que sí debido a la duplicación, pero quizás no?

Además, tenemos otra duplicación de documentación similar con las funciones override y las funciones virtual .

¿Esto es malo y debería evitarse, o no? ¿Vale la pena incluso?

    
pregunta Earlz 04.04.2013 - 17:31

1 respuesta

7

En general, solo agregaría nueva documentación a los métodos de la implementación si hay algo específico acerca de esa que se debe mencionar.

En javadoc puede vincular a otros métodos, lo que le permitiría simplemente 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 (según mi lectura de la documentación en línea, no 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 elemento <see/> : enlace

    
respondido por el FrustratedWithFormsDesigner 04.04.2013 - 17:46

Lea otras preguntas en las etiquetas

Diseño genérico de analizador de archivos en Java usando el patrón de Estrategia Cómo hacer que un sitio ASP.NET MVC sea modular