Wie gehe ich mit Tautologie in Kommentaren um? [geschlossen]

Manchmal finde ich mich in Situationen wieder, in denen der Teil des Codes, den ich schreibe, so selbstverständlich ist (oder zu sein scheint ), dass der Name im Grunde genommen als Kommentar wiederholt wird:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

(C # Beispiel, aber bitte beziehen Sie sich auf die Frage als sprachunabhängig).

Ein Kommentar wie dieser ist nutzlos; Was mache ich falsch? Ist es die Wahl des Namens, die falsch ist? Wie könnte ich solche Teile besser kommentieren? Sollte ich den Kommentar für solche Dinge einfach überspringen?

In den meisten Projekten, an denen ich arbeite, bleibt nicht viel Zeit, um detaillierte Kommentare zu jedem einzelnen Klassenmitglied zu schreiben.

Das heißt nicht, dass keine Zeit für Kommentare ist. im Gegenteil, es gibt viel Zeit für tautologische Kommentare, die eine umformulierte Version dessen, was kommentiert wird, zurückwerfen. Sie funktionieren hervorragend als Ausgangspunkt .

Insbesondere in Anbetracht der Verwendung von Kommentaren in Visual Studio, die mit IntelliSense geliefert werden , ist es eine gute Idee, mit einer kurzen Information über das Feld zu beginnen:

class Example
{
    /// <summary>
    /// The location of the update.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Und wenn Sie sich beim weiteren Codieren nicht mehr erinnern können, an welchem UpdateLocationOrt das Update stattgefunden hat oder an welchen Ort das Update gesendet wird, müssen Sie den Code erneut aufrufen. An dieser Stelle sollten Sie die folgenden zusätzlichen Informationen hinzufügen:

class Example
{
    /// <summary>
    /// The Uri location where the update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Wenn Sie ein anderer Programmierer nach Details zu einem Feld fragt, aktualisieren Sie die Kommentare mit diesen Informationen:

Welche Art von Update sollte Example.UpdateLocationzum Speichern verwendet werden?

class Example
{
    /// <summary>
    /// The Uri location where the Foo update took place.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

Genauso wie ein Programm Fehler aufweist, weisen gute Kommentare Fehler auf, die iterativ behoben werden müssen. Der Zweck von Kommentaren besteht darin, das Verständnis des Codes zu verbessern, wenn Sie ihn ein halbes Jahr später erneut aufrufen und sich nicht mehr an die Funktionsweise des Programms erinnern können.

Und genau wie beim Programmieren müssen Ihre Kommentare irgendwo beginnen. Tautologische Kommentare sind Hello World!Kommentare, wenn Sie das Schreiben und Aktualisieren von Dokumentationen üben, wird Ihre Startdokumentation immer widerstandsfähiger.

Kommentare sollten niemals Ihren Code duplizieren. Kommentare sollten nicht die Frage nach dem " Wie " beantworten, sondern nur nach dem " Warum " und " Was ". Warum ein solcher Algorithmus gewählt wird, was sind die impliziten Annahmen hier (es sei denn, Ihre Sprache ist mächtig genug, um dies mit Typsystemen, Verträgen und Ähnlichem auszudrücken), was ist ein Grund, dies überhaupt zu tun, usw.

Ich würde empfehlen, einen Blick in die Praxis der literarischen Programmierung zu werfen, um sich inspirieren zu lassen.

Kommentare sollten den Code beschreiben , nicht duplizieren. Dieser Kopfzeilenkommentar ist nur doppelt vorhanden. Lass es aus.

Lass sie weg!

Normalerweise empfiehlt es sich, Kommentare zu entfernen, wenn die darin enthaltenen Informationen bereits an anderer Stelle vorhanden sind. Wenn Sie den Zweck einer Methode klar und eindeutig ausdrücken können, indem Sie ihr einen guten Namen geben, ist kein Kommentar erforderlich .

Steck sie ein!

Ihr Beispiel zeigt zwei Ausnahmen von dieser Regel:

Erstens kann "UpdateLocation" (je nach Kontext) mehrdeutig sein. In diesem Fall müssen Sie entweder einen besseren Namen oder einen Kommentar eingeben, um die Mehrdeutigkeit zu beseitigen. Das Verbessern des Namens ist im Allgemeinen die bessere Option, dies ist jedoch nicht immer möglich (wenn Sie beispielsweise eine veröffentlichte API implementieren).

Zweitens gibt das "///" in C # einen Kommentar an, der zum automatischen Generieren von Dokumentation verwendet werden soll. Die IDE verwendet diese Kommentare für QuickInfos, und es gibt Tools (Sandcastle), mit denen Hilfedateien usw. aus diesen Kommentaren generiert werden können. Daher gibt es Argumente für das Einfügen dieser Kommentare, auch wenn die darin dokumentierten Methoden bereits beschreibende Namen haben. Selbst dann würden jedoch viele erfahrene Entwickler die Vervielfältigung von Informationen missbilligen. Ausschlaggebend sollten die Bedürfnisse derjenigen sein, für die die Dokumentation bestimmt ist.

Ich bin mit den Antworten "Schreibe keine Kommentare" überhaupt nicht einverstanden. Warum? Lassen Sie mich darauf hinweisen, indem Sie Ihr Beispiel ein wenig ändern.

public Uri UpdateLocation ();

Was macht diese Funktion also:

• Gibt es den "Update-Ort" zurück? oder
• Wird der Standort "aktualisiert" und der neue Standort zurückgegeben?

Sie können sehen, dass es ohne Kommentar Mehrdeutigkeiten gibt. Ein Neuling kann den Fehler leicht machen.

In Ihrem Beispiel handelt es sich um eine Eigenschaft, sodass die Methoden "get / set" zeigen, dass die zweite Option falsch ist und in der Tat "Ort aktualisieren" und nicht "Ort aktualisieren" bedeutet. Es ist jedoch viel zu einfach, diesen Fehler zu begehen, insbesondere bei mehrdeutigen Wörtern wie "update". Spiele sicher. Verwirren Sie niemanden, der dies noch nicht kennt, nur um ein paar Sekunden Ihrer Zeit zu sparen.

/// <summary>Blöcke werden zum Generieren von Dokumentation für IntelliSense- und API-Dokumentation verwendet .

Wenn also diese eine öffentlich zugängliche API ist, sollten Sie immer zumindest einen <summary>Kommentar, auch wenn der Zweck der Funktion sollte für den Leser selbstverständlich.

Dies ist jedoch die Ausnahme von der Regel. Denken Sie im Allgemeinen nur an DRY (Don't Repeat Yourself) .

Füllen Sie solche Kommentare nur aus, wenn Sie wissen, wie Sie von solchen Dingen profitieren können. ansonsten einfach abwischen.

_{Ein klarer Vorteil für mich war, dass eine automatische Überprüfung auf fehlende Kommentare erfolgte und ich diese Überprüfung verwendete, um den Code zu ermitteln, in dem wichtige Informationen eingegeben werden mussten. Dafür habe ich tatsächlich einige Platzhalter ausgefüllt - nur um sicherzustellen, dass der Tool-Report keine "Fehlalarme" enthält.}

Ich denke, es gibt immer eine Möglichkeit, eine offensichtliche Verdoppelung zu vermeiden . Im Laufe der Jahre habe ich einige "Schablonenfüller" für Fälle wie Ihren verwendet - meistens als selbstbeschreibender Name und siehe oben .

Für dieses spezielle Beispiel würde ich etwas "Selbstbeschreibendes" verwenden (vorausgesetzt, es ist nicht der Fall, dass das Auslöschen den Job erledigen würde):

class Example
{
    /// <summary>
    /// Self descriptive method name.
    /// </summary>
    public Uri UpdateLocation { get; set; };
}

_{Ein Beispiel für die Verwendung der oben genannten Art von Füllzeichen sind Javadoc- Kommentare, für die dedizierte Felder für Rückgabewerte, Parameter und Ausnahmen erforderlich sind. Sehr häufig finde ich, dass es sinnvoller ist, die meisten oder sogar alle in einem einzigen zusammenfassenden Satz zu beschreiben, einer Methode, die für bereitgestellte Parameter <describe parameters> <describe parameters> zurückgibt, was zurückgegeben wird . In solchen Fällen , dass fülle ich formal erforderlichen Felder mit einfachen oben sehen , zeigt Leser zusammenfassende Beschreibung.}

Hier ist eine Frage, die ich mir gerne stelle, wenn ich überlege, ob ich einem Codeabschnitt einen Kommentar hinzufügen soll: Was kann ich vermitteln, das der nächsten Person hilft, die allgemeine Absicht des Codes besser zu verstehen , damit sie ihn aktualisieren, korrigieren oder verbessern kann? Verlängern Sie es schneller und zuverlässiger?

Manchmal ist die richtige Antwort auf diese Frage, dass Sie an dieser Stelle im Code nicht viel hinzufügen können, da Sie bereits Namen und Konventionen ausgewählt haben, die die Absicht so offensichtlich wie möglich machen. Das heißt, Sie haben einen soliden selbstdokumentierenden Code geschrieben, und das Einfügen eines Kommentars würde wahrscheinlich mehr beeinträchtigen als helfen. (Beachten Sie, dass redundante Kommentare die Zuverlässigkeit des Codes im Laufe der Zeit beeinträchtigen können, indem sie die Synchronisation mit dem tatsächlichen Code im Laufe der Zeit verlangsamen und es somit schwieriger machen, die tatsächliche Absicht zu entschlüsseln.

In fast jedem Programm und in jeder Programmiersprache werden Sie jedoch auf Punkte stoßen, an denen bestimmte kritische Konzepte und Entscheidungen, die der ursprüngliche Programmierer - von Ihnen - getroffen hat - im Code nicht mehr erkennbar sind. Dies ist so gut wie unvermeidlich, da ein guter Programmierer immer für die Zukunft programmiert - das heißt, nicht nur, um das Programm einmal zum Laufen zu bringen, sondern um all seine vielen zukünftigen Korrekturen und Versionen und Erweiterungen sowie Änderungen und Anschlüsse vorzunehmen und wer weiß, was zu tun ist auch richtig funktionieren. Letzteres ist viel schwieriger und erfordert viel mehr Überlegungen, um erfolgreich zu sein. Es ist auch sehr schwer in den meisten Computersprachen zum Ausdruck bringen, die auf Funktionalität fokussierter sind - das heißt, auf zu sagen , was tut dies Version des Programms muss jetzt tun, um es zufriedenstellend zu machen.

Hier ist ein einfaches Beispiel dafür, was ich meine. In den meisten Sprachen ist eine schnelle Inline-Suche in einer kleinen Datenstruktur so komplex, dass jemand, der sie zum ersten Mal betrachtet, sie wahrscheinlich nicht sofort erkennt. Dies ist eine Gelegenheit für einen guten Kommentar, da Sie etwas über die Absicht Ihres Codes hinzufügen können, das ein späterer Leser wahrscheinlich sofort als hilfreich für die Entschlüsselung der Details einschätzen wird.

Umgekehrt kann es in Sprachen wie der logikbasierten Sprache Prolog so unglaublich trivial und prägnant sein, die Suche in einer kleinen Liste auszudrücken, dass jeder Kommentar, den Sie hinzufügen, nur Rauschen ist. Gutes Kommentieren ist also notwendigerweise kontextabhängig. Dazu gehören Faktoren wie die Stärken der von Ihnen verwendeten Sprache und der gesamte Programmkontext.

Das Fazit lautet: Denken Sie an die Zukunft. Fragen Sie sich, was für Sie wichtig und offensichtlich ist, wie das Programm in Zukunft verstanden und geändert werden soll. [1]

Für diejenigen Teile Ihres Codes, die sich wirklich selbst dokumentieren, fügen Kommentare nur Rauschen hinzu und erhöhen das Kohärenzproblem für zukünftige Versionen. Fügen Sie sie dort also nicht hinzu.

Fügen Sie jedoch für die Teile Ihres Codes, in denen Sie aus mehreren Optionen eine kritische Entscheidung getroffen haben oder in denen der Code selbst so komplex ist, dass sein Zweck undeutlich ist, Ihr spezielles Wissen in Form eines Kommentars hinzu. Ein guter Kommentar in einem solchen Fall ist einer, der einen zukünftigen Programmierer wissen lässt, was beibehalten werden muss - das ist übrigens das Konzept einer invarianten Behauptung - und was geändert werden kann.

[1] Dies geht über die Ausgabe von Kommentaren hinaus, aber es lohnt sich, darauf einzugehen: Wenn Sie feststellen, dass Sie eine sehr genaue Vorstellung davon haben, wie sich Ihr Code in Zukunft ändern könnte, sollten Sie wahrscheinlich über das einfache Erstellen eines Kommentars und das Einbetten dieser Parameter hinausdenken im Code selbst, da dies fast immer eine zuverlässigere Methode ist, um die Zuverlässigkeit zukünftiger Versionen Ihres Codes sicherzustellen, als Kommentare zu verwenden, um unbekannte zukünftige Personen in die richtige Richtung zu lenken. Gleichzeitig möchten Sie auch eine Überverallgemeinerung vermeiden, da Menschen die Zukunft notorisch schlecht vorhersagen können, was auch die Zukunft von Programmänderungen einschließt. Versuchen Sie also, vernünftige und bewährte Dimensionen der Zukunft auf allen Ebenen der Programmgestaltung zu definieren und zu erfassen.

In meinem eigenen Code hinterlasse ich häufig Kommentartautologien, einschließlich der besonders ungeheuerlichen wie:

<?php
// return the result
return $result;
?>

... die offensichtlich wenig dazu beitragen, den Code aus einer erklärenden Perspektive verständlicher zu machen.

Meiner Meinung nach haben diese Kommentare jedoch immer noch Wert, wenn sie dazu beitragen, die visuelle Konsistenz der Farbmuster in Ihrem Syntax-Textmarker zu erhalten .

Ich stelle mir Code mit einer Struktur vor, die der englischen Sprache sehr ähnlich ist, da es "Sätze" und "Absätze" gibt (obwohl ein "Absatz" vollständig aus einem einzigen "Satz" bestehen kann). Ich füge normalerweise einen Zeilenumbruch und eine einzeilige Zusammenfassung über jedem "Absatz" ein. Zum Beispiel:

<?php
//get the id of the thing
$id = $_POST['id'];

//query the things out of the the database
$things = array();
$result = mysql_query("SELECT * FROM Things WHERE `id` = $id");
while ($row = mysql_fetch_assoc($result)) {
    //create a proper Thing object or whatever
    $things[] = new Thing($row);
}

//return the things
return $things;
?>

(Ignorieren Sie den unvollständigen Code, die SQL-Injektionen usw.)

Für mich bringt der abschließende Kommentar einen echten Mehrwert für den Code, einfach weil er hilft, einen "Absatz" von einem anderen optisch abzugrenzen, indem ein konsistentes Farbschema beibehalten wird.

Kommentare sollten verwendet werden, um eine der folgenden Aktionen auszuführen.

1. Informationen, die Dokumentgeneratoren abrufen können. Das kann man nicht unterschätzen, das ist extrem wichtig.
2. Warnungen, warum ein Teil des Codes so ist, wie er ist, und welche anderen Überlegungen. Ich habe mich mit Code befasst, der in 2 Programmiersprachen geschrieben wurde. Ein wesentlicher Teil davon bestand darin, eine gemeinsame Struktur zwischen den beiden Sprachen zu haben. Ein Kommentar an beiden Stellen, der den Benutzer darüber informiert, dass er, wenn er diese Nummer ändert, auch eine andere ändern muss, ist äußerst hilfreich.
3. Schreiben Sie Notizen, um zu erklären, warum ein besonders seltsam aussehender Code so ist, wie er ist. Wenn Sie darüber nachdenken mussten, wie ein Teil des Codes auf eine bestimmte Art und Weise funktioniert, und die Lösung nicht von Anfang an ersichtlich ist, ist es wahrscheinlich eine Erklärung wert, was Sie versucht haben, zu tun.
4. Beschriftung von Ein- / Ausgängen, wenn diese nicht eindeutig sind. Es ist immer gut zu wissen, wie Ihre Eingaben aussehen sollen und in welchem ​​Format sie vorliegen.

Kommentare sollten nicht verwendet werden, um Folgendes zu tun:

1. Erklären Sie Dinge, die sehr offensichtlich sind. Ich sah einmal Legacy - Code wie folgt aus : page=0; // Sets the page to 0. Ich denke, jeder kompetente Einzelne könnte das herausfinden.

Ich würde die Tautologie entfernen, aber den Kommentar behalten. Ich würde Eigenschaften und Variablennamen kommentieren, indem ich einen Beispielwert gebe, damit die Verwendung klar verstanden wird:

property UpdateLocation:TUpdateLocation;  // url="http://x/y/3.2/upd.aspx",proto=http

Jetzt weiß ich genau, was darin vorgeht, und aus dem Kommentar habe ich eine klare Vorstellung, wie ich es verwenden soll.

Ich würde sagen, es hängt vom Zweck der Kommentare ab.

Wenn sie verwendet werden sollen, um Dokumentation für das Team zu generieren, das sie erstellt (oder wenn sie nur Inline-Kommentare sind, um die Dinge zu erklären), ist es meines Erachtens akzeptabel, dies wegzulassen. Es ist davon auszugehen, dass es selbsterklärend ist. und wenn dies nicht der Fall ist, gibt es andere Teammitglieder in der Nähe, die es erklären können. Natürlich, wenn sich herausstellt, dass es für viele Menschen nicht selbstverständlich ist, sollten Sie es hinzufügen.

Wenn aus den Kommentaren eine Dokumentation für ein geografisch entferntes Team erstellt wird, würde ich jedes Dokument dort ablegen.

Ich denke, dieses Thema wurde ziemlich ausführlich unter Namen wie "Kommentare: Antimuster" oder "Sind Kommentare ein Codegeruch?" ( ein Beispiel ).

Ich stimme der allgemeinen Idee zu, dass Kommentare neue Informationen hinzufügen und nicht duplizieren sollten. Indem Sie so triviale Kommentare hinzufügen, verletzen Sie DRY und verringern das Signal-Rausch-Verhältnis des Codes. Ich finde in der Regel allgemeine Kommentare, die die Verantwortlichkeiten, die Hintergründe und die Beispielnutzung der Klasse erklären, viel nützlicher als Kommentare pro Eigenschaft (insbesondere überflüssige).

Persönlich würde ich in Ihrem Beispiel einen Kommentar weglassen (wenn es wirklich nichts Nützliches gibt, das zu der Eigenschaft hinzugefügt werden könnte).

Wenn Sie Code schreiben können, für den keine Kommentare erforderlich sind, haben Sie das Programmieren von Nirvana! Erreicht.

Je weniger Kommentare Ihr Code benötigt, desto besser ist der Code!

Ein Kommentar wie dieser ist nutzlos; Was mache ich falsch?

Es scheint nur nutzlos, wenn Sie bereits wissen, was UpdateLocationtut. Ist "update" hier ein Verb oder ein Nomenzusatz? Ist dies etwas, das den Speicherort aktualisiert, oder ist es der Speicherort des Updates? Letzteres könnte man aus der Tatsache ableiten, dass UpdateLocationes sich anscheinend um eine Eigenschaft handelt, aber der größere Punkt ist, dass es manchmal nicht schadet, ausdrücklich etwas anzugeben, das offensichtlich erscheint.

Abgesehen von der automatisch kompilierten Dokumentation sollte sich der Code selbst dokumentieren, sodass Kommentare nur dort dokumentieren sollten, wo der Code nicht ausreicht, um sich selbst zu dokumentieren.

"Location" ist ein bisschen offensichtlich, aber "Update" könnte ein bisschen vage sein. Wenn Sie keinen besseren Namen schreiben können, können Sie dann mehr Details im Kommentar angeben? Update von was? Warum brauchen wir das? Was sind einige Annahmen (ist null zulässig)?