Duplication de la documentation sur les implémentations / remplacements d'interfaces bonne ou mauvaise?

20

Nous avons donc une interface comme ça

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

Récemment, nous avons joué une histoire de documentation qui impliquait de générer et de s'assurer qu'il y avait beaucoup de documentation XML comme ci-dessus. Cela a cependant causé beaucoup de duplication de la documentation. Exemple d'implémentation:

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

Comme vous pouvez le voir, la documentation de la méthode est une extraction directe de l'interface.

La grande question est, est-ce une mauvaise chose? Mon instinct me dit oui à cause de la duplication, mais là encore peut-être pas?

En outre, nous avons d'autres duplications de documentation similaires avec des overridefonctions et des virtualfonctions.

Est-ce mauvais et devrait être évité ou non? Est-ce que cela en vaut même la peine?

c# documentation xml documentation-generation Earlz
la source
Si vous utilisez Resharper, vous pouvez modifier les commentaires uniquement dans l'implémentation, puis mettre à jour l'interface en utilisant "Tirer les membres vers le haut".
vortexwolf
Je le fais, mais peut-être parce que je ne suis pas très doué pour utiliser des outils externes et préfère simplement aller dans le fichier d'en-tête d'une interface pour voir ce que je peux faire avec un type de chose particulier (c'est pour C et C ++ qui séparent la notion d'en-tête du fichier source). Cela devient un peu répétitif, mais j'essaie de trouver des opportunités pour ajouter des détails plus spécifiques concernant la classe concrète en remplaçant les méthodes, par exemple, j'aime ça et j'ai un truc OCD où j'ai l'impression d'avoir omis quelque chose d'important si je ne le fais pas voir les commentaires pour chaque fonction dans un fichier d'en-tête.
J'utilise en fait des commentaires et des balises Doxygen, mais je ne regarde pas tellement les documents en cours de codage. Je préfère simplement naviguer vers le fichier d'en-tête et voir ce que je peux faire avec quelque chose. Cela pourrait simplement être le cas d'un vieux chien qui a du mal à acquérir de nouvelles habitudes et de nouveaux outils.

Réponses:

9

En général, je n'ajouterais une nouvelle documentation aux méthodes de l'implémentation que si cette implémentation doit être mentionnée.

Dans javadoc, vous pouvez créer un lien vers d'autres méthodes, ce qui vous permettrait de créer simplement un lien dans l'implémentation vers la documentation de la méthode dans l'interface. Je pense que c'est ainsi que cela est censé se faire dans .Net (basé sur ma lecture de la documentation en ligne, pas sur ma propre expérience):

/// <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 documentation de l' <see/>élément: http://msdn.microsoft.com/en-us/library/acd0tfbe.aspx

FrustratedWithFormsDesigner
la source
Que diriez-vous de remplacer les documents XML dans une classe héritée? Supposons que je crée une sous-classe de Collection<T>et souhaite remplacer sa Countdocumentation XML de propriété.
Shimmy