Wie sollte Kommentare für Schnittstelle und Klassenmethoden unterschiedlich sein

Question

Ich lief in diesem Dilemma, wenn sie auf einer ASP.net Web-Anwendung arbeitet mit dem Web Client Software Factory (WCSF) in C # und das gleiche für andere Plattform und Sprachen Anwendung finden könnte. Meine Situation ist wie folgt:

Ich bin die Definition ein I View-Schnittstelle für jede Web-Seite / Steuer Benutzer basierend auf WCSF Paradigma, hat dann die Seite Klasse implementieren, um die I View-Schnittstelle, Implementierung grundsätzlich jede der in der Schnittstelle definierten Methoden . Als ich versuchte, xml-Dokumentation auf der Methode Ebene hinzuzufügen, fand ich mich im Grunde den gleichen Kommentar Inhalt für beiden Schnittstellenverfahren zu wiederholen, und sein Gegenstück in der implementierenden Klasse.

Also meine Frage ist: sollte es einige wesentliche Unterschied zwischen dem Inhalt der Dokumentation auf der Interface-Methode und der entsprechenden Klassenmethode? Sollten sie auf anderen Aspekt oder etwas betont werden?

Jemand hat mir gesagt, dass der Interface-Methode Kommentar sagen sollte, „was“ das Verfahren tun soll, und die Klassenmethode Kommentar sagen sollte, „wie“ sie es tut. Aber ich erinnere mich irgendwo zu lesen, bevor dass die Methode Ebene Kommentar sollte nur sagen, „was“ das Verfahren tun soll, nie die Umsetzung Detail des Verfahrens, da die Umsetzung kein Problem für die Methode Benutzer sein sollte, und es könnte sich ändern.

Answer 1

Ich persönlich denke, diese Kommentare die gleiche sein sollen - beide sagen sollen „was die Methode tun wird“, in den Begriffen

.

Es gibt keinen Grund für XML-Kommentare Implementierungsdetails zu erwähnen. Die einzige Ausnahme, möglicherweise würde mögliche Nebenwirkungen zu erwähnen. (Dh: diese Methode eine lange Zeit dauern kann), aber ich persönlich würde diesen Abschnitt der XML-doc Kommentare in dem <remarks> tun

Answer 2

Rufen Sie mich an eine Mutter, aber ich würde einen beschreibenden Namen für die Methode verwenden, und nennen ihn einen Tag (keine Kommentare entweder). Ich könnte Kommentare zur Umsetzung hinzufügen, wenn etwas dagegen ist überraschend, oder warum die es nicht nahe liegend.