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

54

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?

Tamás Szelei
quelle
8
Hinweis: Ich würde "Die Position des Updates" als sehr vage betrachten, es sei denn, es ist klar, was "ein Update" ist. Unterstützt das System andere Arten von URIs als URLs?
34
return result # returns result
Lukas Stejskal
27
Der Umgang mit Tautologie in Kommentaren ist der Umgang mit Tautologie in Kommentaren. (Dies ist ein Kommentar.)
Rex Kerr
29
Dies ist eigentlich kein Kommentar, sondern eine Dokumentation in Form eines Kommentars. Für die API-Dokumentation gelten andere Regeln als für Inline-Codekommentare.
Cody Grey
10
Dies ist nur ein Beispiel für eine schlechte API-Dokumentation, keine Codekommentare. Meine C # XML-Formatierung für eine Eigenschaft wie diese würde ungefähr so ​​aussehen: "Ruft einen Uri ab, der für den Zugriff auf den Aktualisierungsserver dieses Objekts verwendet werden kann, oder legt diesen fest."
Kevin McCormick

Antworten:

13

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.

zzzzBov
quelle
+1 für die einzige Person, die tatsächlich einen alternativen Kommentar abgibt; eher als nur tautologische Antworten.
Ian Boyd
Dies ist derzeit die beste Antwort.
Roland Tepp
1
In meinem aktuellen Projekt wurde ich mehr getroffen, als ich durch das Fehlen von Kommentaren zu einer großen Legacy-Codebasis zählen kann. Etwas, das Sie als Autor für offensichtlich selbsterklärend halten, ist ein Methodenname für etwas, das Sie als ziemlich offensichtliche Funktionalität erachten und das für einen anderen Entwickler in drei Monaten möglicherweise nicht so selbstdokumentierend ist. Die Dokumentation zu Methoden, Eigenschaften und Feldern sollte versuchen, einen Kontext für das Gesamtbild zu erstellen. Diese Antwort erklärt den besten Prozess, um dieses Ziel zu erreichen, den ich bisher gesehen habe.
Roland Tepp
1
@ RolandTepp, ich verstehe vollkommen, woher Sie kommen. Und ich stimme vollkommen zu. Das Problem ist meines Erachtens, dass viele Programmierer Kommentare und Dokumentation als etwas ansehen, das nach Fertigstellung und Versand des Codes geschieht, und nicht als etwas, das mit dem Code als Teil des Entwicklungsprozesses geschieht und das Fehlerverfolgung und Supportstunden erfordert zusammen mit dem Rest des Codes.
zzzzBov
54

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.

SK-Logik
quelle
+1 - das ist die Antwort! Wir brauchen keine Kommentare wie "Variablen deklarieren", "Inkrementzähler" (in einer Schleife) usw.
ozz
Was wäre also im Beispiel des OP ein guter Kommentar?
29.
4
@stijn, ich weiß es nicht - es fehlt (offensichtlich) im Code. Etwas, das nur der Autor des Codes über seinen Zweck und seine Einschränkungen weiß.
SK-logic am
Vielleicht ein Kommentar wie // Aktualisiert die raiseShielders entsprechend dem levelOfAttack (als URL übergeben)
woliveirajr
15
Die wichtigste Frage, die ein Kommentar beantworten sollte, ist " WTF? "
naught101
53

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

mjfgates
quelle
17
+1: Ich glaube, ich verstehe, was Sie meinen, aber ich stimme nicht mit dem überein, was Sie gesagt haben :-) Soweit möglich, sollte Code Code beschreiben, während Kommentare Ihre Argumentation beschreiben sollten.
Kramii setzt Monica am
3
@Kramii, leider kann Code den Code nicht beschreiben , auch wenn Sie in Agda codieren. Keine Sprache ist so kraftvoll und ausdrucksstark wie die natürliche Sprache. Und häufig benötigen Sie Diagramme, Grafiken, Tabellen und komplexe Formeln, um den Code zu beschreiben - kaum möglich ohne eine ordnungsgemäße Programmierung.
SK-logic
6
@ SK-Logik: Ich bin anderer Meinung. Eine lange Methode ist weniger selbsterklärend als eine kurze Methode, die eine Reihe von gut benannten Unterroutinen aufruft.
Kramii Reinstate Monica
3
@Kramii, sorry, ich kann nicht sehen, womit du nicht einverstanden bist und inwiefern sich dein Kommentar auf das bezieht, was ich gesagt habe. Mein Punkt ist, dass neben Ihrem Code viele Informationen bereitgestellt werden sollten, die im Code selbst völlig fehlen . Die ganze Geschichte hinter den von Ihnen getroffenen Entscheidungen, alle relevanten Verweise auf die Beiträge usw. - es gibt keine Sprachelemente, um solche Dinge auszudrücken. Und lange vs. kurze Methoden / Funktionen / Unterprogramme / was auch immer hier völlig irrelevant ist.
SK-logic
2
@ SK-logic, was Kramii sagt, bedeutet: "Der Code sollte einfach zu lesen und zu verstehen sein", und alle Grafiken usw., die Sie erwähnen, fallen unter das, was er sagt: "Die Kommentare sollten Ihre Argumentation beschreiben"
Shahbaz
36

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.

Kramii setzt Monica wieder ein
quelle
Das ist die beste Antwort. Sie sollten in der Lage sein, genau herauszufinden, wofür die Eigenschaft verwendet wird, wenn Sie die Example-Klasse verwenden und den Mauszeiger über die Eigenschaft halten.
Andy
In diesen Situationen bemühe ich mich (und scheitere oft), mindestens einen <remarks/>oder mehrere hinzuzufügen <see/>, um zusätzlichen Inhalt bereitzustellen. Das <summary/>ist zwar noch vervielfältigt, aber der Kommentar insgesamt ist nicht ganz unbrauchbar.
EarlNameless
20

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.

DPD
quelle
4
Ich glaube nicht, dass jemand befürwortet, überhaupt keine Kommentare zu schreiben. Die meisten / alle sagen "Entsprechende Kommentare schreiben", worunter das UpdateLocation-Beispiel fallen würde.
ozz
16
Uri UpdateLocation()würde durch Codeüberprüfung abgelehnt und in entweder Uri GetUpdateLocation()oder in geändert void UpdateLocation().
Avakar
4
@avakar: Stimmen Sie dem Gefühl zu, aber da dies eine C # -Eigenschaft ist (get und set werden automatisch synthetisiert und haben denselben Namen), GetUpdateLocationwürde das Umbenennen zu Code wie führen GetUpdateLocation = somelocation. LocationOfUpdatewäre ein besserer Name, der die Mehrdeutigkeit beseitigt. Das Grundproblem ist, dass das OP ein Verbpräfix anstelle eines Substantivs verwendete. Es wird angenommen, dass führende Verben die Wirkung einer Methode angeben.
Ant
2
@DPD, "Wie viel Zeit und Mühe ist nötig, um eine Leitung zu verbinden?" Wie viel Mühe ist nötig, um sie zu warten? Wie viel Bildschirmfläche verschwendet es? Wie viel Zeit wird verschwendet, wenn es letztendlich nicht mehr mit dem Code synchronisiert ist und Entwickler verwirrt?
Avakar
1
Die Methode gibt einen Wert zurück und hat einen Verbphrasennamen. Das ist das Problem. Es sollte einen Nominalphrasennamen haben. zB 'Uri LocationOfUpdate ()'. Nicht GetUpdateLocation, sagen Sie "Was ist Ihre GetLocation?"
Strg-Alt-Delor
14

/// <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) .

Peter Mortensen
quelle
5

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.

Mücke
quelle
3

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.

Terry Bollinger
quelle
3

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.

chrisallenlane
quelle
Es fällt mir schwer, die Syntaxhervorhebung in meiner Antwort hier zum Funktionieren zu bringen. Wenn ein Redakteur hinter mich kommen und es zum Laufen bringen kann, würde ich es wirklich begrüßen, da die Farben für mein Argument von Bedeutung sind.
Chris Allen Lane
Ich habe Sprachhinweise zur Syntaxhervorhebung für Sie hinzugefügt .
Paŭlo Ebermann
2

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.
PearsonArtPhoto
quelle
2

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.

Warren P
quelle
0

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.

Andy Hunt
quelle
0

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).

Daniel B
quelle
0

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!

James Anderson
quelle
3
Dies ist nicht möglich (und wird es niemals tun). Es bleibt immer viel hinter dem Code zurück - implizite Annahmen, Architekturentscheidungen, lange Ketten mathematischer Transformationen, die in einem bestimmten Algorithmus enden usw.
SK-logic
1
Vielleicht "Hallo Welt!" ist Programmierer Nirwana dann ...
naught101
: -} - Es ist etwas, das sehr selten erreicht wird. Der Punkt ist, wenn Sie Schwierigkeiten haben, einen Kommentar zu finden, der Bedeutung hinzufügt, dann seien Sie einfach zufrieden mit sich selbst. Das bedeutet, dass Ihr Code genau richtig ist!
James Anderson
0

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.

Caleb
quelle
0

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.

Ando
quelle
-1

"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)?

Scott Whitlock
quelle