Wie sollten Kommentare für Schnittstellen- und Klassenmethoden anders sein?

Ich bin in dieses Dilemma geraten, als ich an einer ASP.net-Webanwendung unter Verwendung von Webclient Software Factory (WCSF) in C# gearbeitet habe. Dasselbe könnte auch für andere Plattformen und Sprachen gelten. Meine Situation ist wie folgt aus:Wie sollten Kommentare für Schnittstellen- und Klassenmethoden anders sein?

ich eine I View-Schnittstelle für jede Web-Seite/Benutzersteuerung am definieren basierend auf WCSF Paradigma, haben dann die Seite Klasse die ich View-Schnittstelle implementieren, im Grunde jede der Methoden der Umsetzung definiert in die Schnittstelle. Als ich versuchte, XML-Dokumentation auf der Methodenebene hinzuzufügen, wiederholte ich den gleichen Kommentarinhalt für beide Interface-Methoden und ihren Gegenpart in der implementierenden Klasse.

Meine Frage ist also: sollte es einen wesentlichen Unterschied zwischen dem Dokumentationsinhalt auf der Interface-Methode und der entsprechenden Klassenmethode geben? Sollten sie einen anderen Aspekt oder etwas betonen?

Jemand sagte mir, dass der Kommentar der Interface-Methode sagen sollte, "was" die Methode tun soll, und der Kommentar der Klassenmethode sollte sagen "wie" es das tut. Aber ich erinnere mich, irgendwo vorher gelesen zu haben, dass der Kommentar auf Methodenebene nur sagen sollte, "was" die Methode tun sollte, niemals die Implementierungsdetails der Methode, da die Implementierung kein Problem für Methodenbenutzer sein sollte und sich ändern könnte.

Quelle

2010-03-05 hongliang

Ich persönlich denke, diese Kommentare sollten die gleichen sein - beide sollten sagen, "was die Methode wird", in Ihren Worten.

Es gibt keinen Grund für XML-Kommentare, Implementierungsdetails zu erwähnen. Die einzige Ausnahme wäre möglicherweise die Erwähnung potenzieller Nebenwirkungen (dh: diese Methode kann lange dauern), aber ich persönlich würde das im Abschnitt <remarks> der Kommentare zum XML-Dokument tun.

Quelle

2010-03-05 19:24:43

Dies ist die Antwort, vor der ich eigentlich Angst hatte :), aber ich denke, Sie haben Recht. Ich werde getragen und wiederhole den gleichen Inhalt an beiden Orten. Copy-n-Paste half, es zu beschleunigen, aber die Tatsache, dass ich das mache, schreckt mich ... – hongliang

@Hongliang: Wenn Sie eine Schnittstelle implementieren, erhalten Sie eine Kopie von GhostDoc - Sie können einen einzigen Schlüssel verwenden, um XML-Dokument-Kommentare für die implementierende Klasse auszufüllen und die Kommentare von der Schnittstelle zu kopieren. Sehr glatt: http://submain.com/products/ghostdoc.aspx –

Wow! Genau das möchte ich. Vielen Dank! – hongliang

Nennen Sie mich eine Nuss, aber ich würde einen beschreibenden Namen für die Methode verwenden und es einen Tag nennen (keine Kommentare für beide). Ich könnte der Implementierung Kommentare hinzufügen, wenn etwas daran überraschend ist oder warum es nicht offensichtlich ist.

Quelle

2010-03-05 19:24:07

stimme ich eigentlich ziemlich stark. Kommentarmethoden (mit kurzen, aussagekräftigen Kommentaren) mit XML-Dokumentenkommentaren sind sehr wertvoll, besonders wenn es sich um eine API handelt, die von anderen verwendet werden kann ... Es gibt keinen Ersatz für die aussagekräftigen Nachrichten in intellisense, die Sie aus XML-Dokumentenkommentaren erhalten. –

Danke. Ich stimme zu, dass der Name deskriptiv sein sollte, was Kommentare überflüssig macht. Dennoch, meine eigene Erfahrung sagt mir manchmal, es gibt nur so viel, was man mit einem Namen sagen kann - es sei denn, man stört sich nicht lächerlich lange Namen mit "When" s und "If" s drin. – hongliang

Wenn der Aufrufer sich mit allen when/ifs befassen muss, wie eine Methode implementiert ist, deren Aufruf ausgeführt wird, ist das Design-Feedback, dass Ihre Objekte zu viel Kopplung haben. –

Wie sollten Kommentare für Schnittstellen- und Klassenmethoden anders sein?

Antwort

Verwandte Themen