Code-Kommentierung: Setzen Sie Ihre Code-Kommentare auf Interfaces oder auf Concrete-Klassen oder beides?

Question

Was ist die beste Vorgehensweise beim Dokumentieren von Klassen und Schnittstellen? Angenommen, Sie haben eine konkrete Klasse namens Foo, die von einer Schnittstelle namens IFoo stammt. Wo stellst du deine Kommentare für deine Methoden ein? Vervielfältigen Sie Ihre Kommentare sowohl an der Oberfläche als auch an der konkreten Klasse? Hier

ist ein Beispiel, in dem Kommentare dupliziert werden:

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

public interface IFoo 
{ 
    /// <summary> 
    /// This function does something 
    /// </summary>   
    void DoSomething(); 
} 

Answer 1

ich Kommentare zu beiden setzen würde.

Auf Schnittstellen würde ich die Absicht hinter den Schnittstellenmitgliedern und der Verwendung kommentieren.

Bei Implementierungen würde ich die Gründe für die spezifische Implementierung kommentieren.

Answer 2

ich sie im Allgemeinen auf beide setzen sie jedoch nicht das gleiche sagen. Der Kommentar der Schnittstelle sollte den abstrakten Zweck dieser Methode/Schnittstelle beschreiben. Während der konkrete Kommentar im Kontext des Zwecks der Schnittstelle über die Implementierungsspezifika der Methode/Klasse spricht.

Answer 3

Ich steckte sie in beide, aber es ist ein Schmerz, sie synchron zu halten, im Zweifelsfall habe ich sie nur auf die Schnittstelle gesetzt.

Ich tue dies, weil ich den Tooltip mögen, wenn Sie den Code verwenden, die fast immer die Schnittstelle verwenden sollten ...

Answer 4

Ich benutze sie überhaupt nicht wirklich. Stattdessen sorge ich dafür, den Code zu strukturieren und alle Methoden und Variablen auf eine Weise zu benennen, die offensichtlich ist, was sie ohne Kommentare tun. Das Problem mit Kommentaren besteht darin, dass sie nicht kompiliert werden und nicht ausgeführt werden und nicht von Ihren Komponententests getestet werden, so dass es ziemlich unmöglich ist, sie synchron mit dem Code zu halten.

Answer 5

Nur für Schnittstellen. Weil ich sie in diesem Fall nicht synchronisieren muss. Meine IDE hilft mir, Interface-Kommentare in konkreten Klassen zu sehen. Und ein API-Dokumentengenerator macht das Gleiche.

Answer 6

Beide, aber ich wünschte, es in Funktionalität gebaut wurde, um sie synchron zu halten

Answer 7

Ihr Beispielcode nicht explizite Schnittstellenimplementierung nicht verwendet. Der Client Ihres Codes wird beide benötigen, da er die Methode entweder über ein Klassenobjekt oder eine Schnittstellenreferenz aufrufen kann. Bei expliziter Schnittstellenimplementierung können Sie den Klassenmethodenkommentar weglassen, da der Client ihn nie sehen kann. Dies setzt voraus, dass Sie die XML-Dokumentation zum Generieren von IntelliSense-Informationen verwenden.

Answer 8

Ein Tag <referTo>System. .... </referTo> verlinkt Kommentare würden

Answer 9

Idealerweise nur die Schnittstelle zu dokumentieren muss ideal sein, da sie den Vertrag definiert, dass jede konkrete Umsetzung erfüllen muss.