Code Commentant: Est-ce que vous mettez vos commentaires de code sur les interfaces ou classes concrètes, ou les deux? [dupliquer]

StackOverflow https://stackoverflow.com/questions/1875440

  •  18-09-2019
  •  | 
  •  

Question

    

Cette question a déjà une réponse ici:

         

Quelle est la meilleure pratique dans la documentation des classes et des interfaces. Dites si vous avez une classe concrète appelée Foo, qui dérive d'une interface appelée IFoo. Où placez-vous vos commentaires pour vos méthodes? Avez-vous dupliquez vos commentaires sur l'interface ainsi que la classe concrète?

Voici un exemple où les commentaires sont dupliqués: 

public class Foo : IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    public void DoSomething()
    {
    }
}

public interface IFoo
{
    /// <summary>
    /// This function does something
    /// </summary>        
    void DoSomething();
}
Était-ce utile?

La solution

Je mettrais des commentaires sur les deux.

Sur les interfaces je commenter l'intention derrière les membres de l'interface et l'utilisation.

Sur les implémentations je commenter les raisons de la mise en œuvre spécifique.

Autres conseils

Je les ai mis généralement sur les deux, cependant, ils ne disent pas la même chose. Le commentaire de l'interface devrait décrire l'objectif de cette méthode abstraite / interface. Alors que le commentaire concret parlera au sujet des détails de mise en œuvre de la méthode / classe dans le cadre de l'objectif de l'interface.

Je les mets dans les deux, mais sa douleur les maintenir synchronisés, en cas de doute, je les ai mis que sur l'interface.

Je le fais parce que j'aime l'info-bulle lorsque vous utilisez le code, qui devrait presque toujours en utilisant l'interface ...

Votre code exemple ne pas utiliser l'implémentation d'interface explicite. Le client de votre code va avoir besoin à la fois depuis qu'il / elle peut invoquer la méthode, soit par un objet de classe ou de référence d'interface. Avec la mise en œuvre d'interface explicite vous pouvez omettre la méthode de classe commentaire puisque le client ne peut jamais le voir. Ceci suppose que vous utilisez la documentation XML pour générer des informations de IntelliSense.

Les deux, mais je souhaite qu'il y ait une fonctionnalité intégrée pour les maintenir synchronisés

Une balise <referTo>System. .... </referTo> pour relier les commentaires serait idéal

Je ne pas vraiment les utiliser du tout. Au lieu de cela je me assure de structurer le code et le nom de toutes les méthodes et les variables d'une manière que son évidente ce qu'ils font sans commentaires. Le problème avec les commentaires est qu'ils ne compilent pas et n'exécutent pas et ne sont pas testés par vos tests unitaires, de sorte que son à peu près impossible de les garder en phase avec le code.

Seulement pour les interfaces. Parce que dans ce cas, je ne ai pas besoin de les synchroniser. Mon IDE me permet de voir les commentaires d'interface dans les classes concrètes. Et un générateur de documents api fait la même chose.

Idéalement, seule l'interface doit être documentée, car il définit le contrat que chaque mise en œuvre concrète doit remplir.

Licencié sous: CC-BY-SA avec attribution
Non affilié à StackOverflow
scroll top