it-swarm.com.de

Clean Code-Kommentare im Vergleich zur Klassendokumentation

Ich habe einige Diskussionen mit meinen neuen Kollegen über das Kommentieren. Wir beide mögen Clean Code, und ich bin vollkommen in Ordnung mit der Tatsache, dass Inline-Code-Kommentare und diese Klasse vermieden werden sollten und Methodennamen sollten verwendet werden, um auszudrücken, was sie tun.

Ich bin jedoch ein großer Fan des Hinzufügens kleiner Klassenzusammenfassungen, die versuchen, den Zweck der Klasse und die tatsächlichen Darstellungen zu erklären, vor allem, damit das Prinzip der Einzelverantwortung Muster leicht beibehalten werden kann. Ich bin es auch gewohnt, Methoden einzeilige Zusammenfassungen hinzuzufügen, die erklären, was die Methode tun soll. Ein typisches Beispiel ist die einfache Methode

public Product GetById(int productId) {...}

Ich füge die folgende Methodenübersicht hinzu

/// <summary>
/// Retrieves a product by its id, returns null if no product was found.
/// </summary

Ich glaube, dass die Tatsache, dass die Methode null zurückgibt, dokumentiert werden sollte. Ein Entwickler, der eine Methode aufrufen möchte, sollte meinen Code nicht öffnen müssen, um festzustellen, ob die Methode null zurückgibt oder eine Ausnahme auslöst. Manchmal ist es Teil einer Schnittstelle, sodass der Entwickler nicht einmal weiß, welcher zugrunde liegende Code ausgeführt wird.

Meine Kollegen denken jedoch, dass diese Art von Kommentaren " Codegeruch " ist und dass "Kommentare immer Fehler sind" ( Robert C. Martin ).

Gibt es eine Möglichkeit, diese Art von Wissen auszudrücken und zu kommunizieren, ohne Kommentare hinzuzufügen? Da ich ein großer Fan von Robert C. Martin bin, bin ich etwas verwirrt. Sind Zusammenfassungen gleich Kommentare und daher immer Fehler?

Dies ist keine Frage zu Inline-Kommentaren.

84
Bjorn

Wie andere bereits gesagt haben, gibt es einen Unterschied zwischen API-dokumentierenden Kommentaren und Inline-Kommentaren. Aus meiner Sicht besteht der Hauptunterschied darin, dass ein Inline-Kommentar neben dem Code gelesen wird, während ein Dokumentationskommentar neben dem Signatur von allem von Ihnen gelesen wird kommentieren.

In Anbetracht dessen können wir das gleiche TROCKENE Prinzip anwenden. Sagt der Kommentar dasselbe wie die Unterschrift? Schauen wir uns Ihr Beispiel an:

Ruft ein Produkt anhand seiner ID ab

Dieser Teil wiederholt nur das, was wir bereits aus dem Namen GetById plus dem Rückgabetyp Product sehen. Es wirft auch die Frage auf, was der Unterschied zwischen "Erhalten" und "Abrufen" ist und welchen Einfluss Code und Kommentar auf diese Unterscheidung haben. Es ist also unnötig und etwas verwirrend. Wenn überhaupt, stört es den tatsächlich nützlichen zweiten Teil des Kommentars:

gibt null zurück, wenn kein Produkt gefunden wurde.

Ah! Das können wir definitiv nicht sicher anhand der Unterschrift wissen und liefern nützliche Informationen.


Gehen Sie jetzt noch einen Schritt weiter. Wenn Leute über Kommentare sprechen, während Code riecht, ist die Frage nicht, ob der Code wie er ist einen Kommentar benötigt, sondern ob der Kommentar angibt, dass der Code besser geschrieben werden könnte, um die Informationen auszudrücken im Kommentar. Das ist es, was "Code-Geruch" bedeutet - es bedeutet nicht "Tu das nicht!", Sondern "Wenn du das tust, könnte es ein Zeichen dafür sein, dass es ein Problem gibt".

Wenn Ihre Kollegen Ihnen sagen, dass dieser Kommentar zu null ein Codegeruch ist, sollten Sie sie einfach fragen: "Okay, wie soll ich das dann ausdrücken?" Wenn sie eine machbare Antwort haben, haben Sie etwas gelernt. Wenn nicht, wird es wahrscheinlich ihre Beschwerden tot töten.


In Bezug auf diesen speziellen Fall ist allgemein bekannt, dass das Nullproblem schwierig ist. Es gibt einen Grund, warum Codebasen mit Schutzklauseln übersät sind, warum Nullprüfungen eine beliebte Voraussetzung für Codeverträge sind und warum die Existenz von Null als "Milliarden-Dollar-Fehler" bezeichnet wurde. Es gibt nicht so viele praktikable Optionen. Eine beliebte in C # gefundene ist jedoch die Try... Konvention:

public bool TryGetById(int productId, out Product product);

In anderen Sprachen kann es idiomatisch sein, einen Typ (oft als Optional oder Maybe bezeichnet) zu verwenden, um ein Ergebnis anzugeben, das möglicherweise vorhanden ist oder nicht:

public Optional<Product> GetById(int productId);

In gewisser Weise hat uns diese Anti-Kommentar-Haltung irgendwohin gebracht: Wir haben zumindest darüber nachgedacht, ob dieser Kommentar einen Geruch darstellt und welche Alternativen für uns existieren könnten.

Ob wir eigentlich diese der ursprünglichen Signatur vorziehen sollten, ist eine ganz andere Debatte, aber wir haben zumindest Optionen, um durch Code auszudrücken, anstatt zu kommentieren, was passiert, wenn kein Produkt gefunden wird. Sie sollten mit Ihren Kollegen besprechen, welche dieser Optionen ihrer Meinung nach besser sind und warum, und hoffentlich dazu beitragen, über pauschale dogmatische Aussagen zu Kommentaren hinauszugehen.

116
Ben Aaronson

Das Zitat von Robert C. Martin wird aus dem Zusammenhang gerissen. Hier ist das Zitat mit etwas mehr Kontext:

Nichts kann so hilfreich sein wie ein gut platzierter Kommentar. Nichts kann ein Modul mehr durcheinander bringen als frivole dogmatische Kommentare. Nichts kann so schädlich sein wie ein alter, mürrischer Kommentar, der Lügen und Fehlinformationen verbreitet.

Kommentare sind nicht wie Schindlers Liste. Sie sind nicht "rein gut". In der Tat sind Kommentare bestenfalls ein notwendiges Übel. Wenn unsere Programmiersprachen ausdrucksstark genug wären oder wenn wir das Talent hätten, diese Sprachen subtil einzusetzen, um unsere Absicht auszudrücken, würden wir nicht sehr viele Kommentare brauchen - vielleicht überhaupt nicht.

Die richtige Verwendung von Kommentaren dient dazu, unser Versäumnis zu kompensieren, sich im Code auszudrücken. Beachten Sie, dass ich den Word-Fehler verwendet habe. Ich meinte es. Kommentare sind immer Fehler. Wir müssen sie haben, weil wir nicht immer herausfinden können, wie wir uns ohne sie ausdrücken können, aber ihre Verwendung ist kein Grund zum Feiern.

Wenn Sie sich also in einer Position befinden, in der Sie einen Kommentar schreiben müssen, überlegen Sie, ob es keine Möglichkeit gibt, den Spieß umzudrehen und sich im Code auszudrücken. Jedes Mal, wenn Sie sich im Code ausdrücken, sollten Sie sich auf den Rücken klopfen. Jedes Mal, wenn Sie einen Kommentar schreiben, sollten Sie eine Grimasse ziehen und das Versagen Ihrer Ausdrucksfähigkeit spüren.

(Kopiert von hier , aber das Originalzitat stammt von Clean Code: Ein Handbuch für agile Software-Handwerkskunst )

Wie dieses Zitat in "Kommentare sind immer Fehler" reduziert wird, ist ein gutes Beispiel dafür, wie manche Leute ein vernünftiges Zitat aus dem Kontext nehmen und es in ein dummes Dogma verwandeln.


API-Dokumentation (wie javadoc) soll die API dokumentieren, damit der Benutzer sie verwenden kann ohne den Quellcode lesen zu müssen. In diesem Fall sollte die Dokumentation erklären, was die Methode tut. Jetzt können Sie argumentieren, dass "Ruft ein Produkt anhand seiner ID ab" redundant ist, da es bereits durch den Methodennamen angezeigt wird, aber die Information, dass null zurückgegeben werden kann, ist definitiv wichtig zu dokumentieren, da dies in keiner vorhanden ist so offensichtlich.

Wenn Sie die Notwendigkeit des Kommentars vermeiden möchten, müssen Sie das zugrunde liegende Problem (dh die Verwendung von null als gültigem Rückgabewert) beseitigen, indem Sie die API expliziter gestalten. Sie könnten beispielsweise eine Art Option<Product> - Typ zurückgeben, sodass die Typensignatur selbst klar kommuniziert, was zurückgegeben wird, falls das Produkt nicht gefunden wird.

In jedem Fall ist es jedoch nicht realistisch, eine API nur durch Methodennamen und Typensignaturen vollständig zu dokumentieren. Verwenden Sie Dokumentkommentare für zusätzliche nicht offensichtliche Informationen, die der Benutzer kennen sollte. Nehmen wir die API-Dokumentation von DateTime.AddMonths() in der BCL:

Die AddMonths-Methode berechnet den resultierenden Monat und das resultierende Jahr unter Berücksichtigung der Schaltjahre und der Anzahl der Tage in einem Monat und passt dann den Tagesteil des resultierenden DateTime-Objekts an. Wenn der resultierende Tag im resultierenden Monat kein gültiger Tag ist, wird der letzte gültige Tag des resultierenden Monats verwendet. Zum Beispiel 31. März + 1 Monat = 30. April. Der Uhrzeitteil des resultierenden DateTime-Objekts bleibt derselbe wie diese Instanz.

Es gibt keine Möglichkeit, dies nur mit dem Methodennamen und der Signatur auszudrücken! Natürlich erfordert Ihre Klassendokumentation möglicherweise nicht diesen Detaillierungsgrad, sondern ist nur ein Beispiel.


Inline-Kommentare sind auch nicht schlecht.

Schlechte Kommentare sind schlecht. Zum Beispiel Kommentare, die nur erklären, was aus dem Code trivial ersichtlich ist. Das klassische Beispiel ist:

// increment x by one
x++;

Kommentare, die etwas erklären, das durch Umbenennen einer Variablen oder Methode oder anderweitige Umstrukturierung des Codes deutlich gemacht werden könnte, sind ein Codegeruch:

// data1 is the collection of tasks which failed during execution
var data1 = getData1();

Dies ist die Art von Kommentaren, gegen die Martin Rails gegen. Der Kommentar ist ein Symptom dafür, dass kein klarer Code geschrieben wurde - in diesem Fall werden selbsterklärende Namen für Variablen und Methoden verwendet. Der Kommentar selbst ist Natürlich nicht das Problem, das Problem ist, dass wir den Kommentar brauchen, um den Code zu verstehen.

Aber Kommentare sollten verwendet werden, um alles zu erklären, was aus dem Code nicht ersichtlich ist, z. warum der Code auf eine bestimmte nicht offensichtliche Weise geschrieben wird:

// need to reset foo before calling bar due to a bug in the foo component.
foo.reset()
foo.bar();

Kommentare, die erklären, was ein übermäßig verschlungener Code bewirkt, sind ebenfalls ein Geruch, aber der Fix besteht nicht darin, Kommentare zu verbieten, der Fix ist der Fix des Codes! Im wirklichen Wort kommt es zwar zu verschlungenem Code (hoffentlich nur vorübergehend bis zu einem Refactor), aber kein gewöhnlicher Entwickler schreibt beim ersten Mal perfekten, sauberen Code. Wenn verschlungener Code auftritt, ist es viel besser, einen Kommentar zu schreiben, der erklärt, was er tut, als nicht einen Kommentar zu schreiben. Dieser Kommentar erleichtert auch die spätere Überarbeitung.

Manchmal ist Code unvermeidlich komplex. Es kann sich um einen komplizierten Algorithmus handeln oder um Code, der aus Leistungsgründen die Klarheit beeinträchtigt. Auch hier sind Kommentare notwendig.

102
JacquesB

Es gibt einen Unterschied zwischen Kommentieren Ihres Codes und Dokumentieren Ihres Codes.

  • Kommentare werden benötigt, um den Code später zu pflegen, dh den Code selbst zu ändern.

    Kommentare können in der Tat als problematisch empfunden werden. Der äußerste Punkt wäre zu sagen, dass sie immer auf ein Problem hinweisen, entweder innerhalb Ihres Codes (Code zu schwer zu verstehen) oder innerhalb der Sprache (Sprache nicht in der Lage) um aussagekräftig genug zu sein; zum Beispiel könnte die Tatsache, dass die Methode niemals null zurückgibt, durch Codeverträge in C # ausgedrückt werden, aber es gibt keine Möglichkeit, dies durch Code in beispielsweise PHP auszudrücken.

  • Dokumentation wird benötigt, um die von Ihnen entwickelten Objekte (Klassen, Schnittstellen) verwenden zu können. Die Zielgruppe ist anders: Es sind nicht die Personen, die Ihren Code pflegen und ändern, über die wir hier sprechen, sondern Personen, die kaum verwenden müssen. es.

    Das Entfernen der Dokumentation, weil der Code klar genug ist, ist verrückt, da die Dokumentation hier speziell dazu dient, Klassen und Schnittstellen zu verwenden, ohne Tausende von Codezeilen lesen zu müssen.

36

Nun, es scheint, Ihr Kollege liest Bücher, nimmt auf, was sie sagen, und wendet das Gelernte an, ohne nachzudenken und ohne Rücksicht auf den Kontext.

Ihr Kommentar zu der Funktion der Funktion sollte so sein, dass Sie den Implementierungscode wegwerfen können. Ich habe den Kommentar der Funktion gelesen und kann den Ersatz für die Implementierung schreiben, ohne dass etwas schief geht.

Wenn der Kommentar mir nicht sagt, ob eine Ausnahme ausgelöst wird oder ob Null zurückgegeben wird, kann ich das nicht tun. Wenn der Kommentar Ihnen nicht sagt , ob eine Ausnahme ausgelöst wird oder ob nil zurückgegeben wird, müssen Sie sicherstellen, wo immer Sie die Funktion aufrufen Ihr Code funktioniert ordnungsgemäß, unabhängig davon, ob eine Ausnahme ausgelöst oder null zurückgegeben wird.

Ihr Kollege liegt also völlig falsch. Und lesen Sie alle Bücher, aber denken Sie selbst.

PS. Ich habe Ihre Zeile gesehen: "Manchmal ist sie Teil einer Schnittstelle, sodass Sie nicht einmal wissen, welcher Code ausgeführt wird." Selbst mit virtuellen Funktionen wissen Sie nicht, welcher Code ausgeführt wird. Schlimmer noch, wenn Sie eine abstrakte Klasse geschrieben haben, gibt es nicht einmal Code! Wenn Sie also eine abstrakte Klasse mit einer abstrakten Funktion haben, sind die Kommentare, die Sie der abstrakten Funktion hinzufügen, die nur Sache, die ein Implementierer einer konkreten Klasse leiten muss. Diese Kommentare können auch das einzige sein, was einen Benutzer der Klasse leiten kann, beispielsweise wenn Sie nur eine abstrakte Klasse und eine Factory haben, die eine konkrete Implementierung zurückgibt, aber niemals einen Quellcode der Implementierung sehen. (Und natürlich sollte ich nicht auf den Quellcode von one Implementierung schauen).

13
gnasher729

Es sind zwei Arten von Kommentaren zu berücksichtigen: diejenigen, die für Personen mit dem Code sichtbar sind, und diejenigen, die zum Generieren von Dokumentation verwendet werden.

Die Art von Kommentar, auf die sich Onkel Bob bezieht, ist nur für Personen mit dem Code sichtbar. Was er befürwortet, ist eine Form von TROCKEN . Für eine Person, die sich den Quellcode ansieht, sollte der Quellcode die Dokumentation sein, die sie benötigt. Selbst wenn Benutzer Zugriff auf den Quellcode haben, sind Kommentare nicht immer schlecht. Manchmal sind Algorithmen kompliziert oder Sie müssen erfassen, warum Sie einen nicht offensichtlichen Ansatz wählen, damit andere Ihren Code nicht beschädigen, wenn sie versuchen, einen Fehler zu beheben oder eine neue Funktion hinzuzufügen.

Die Kommentare, die Sie beschreiben, sind API-Dokumentation. Dies sind Dinge, die für Benutzer Ihrer Implementierung sichtbar sind, die jedoch möglicherweise keinen Zugriff auf Ihren Quellcode haben. Selbst wenn sie Zugriff auf Ihren Quellcode haben, arbeiten sie möglicherweise an anderen Modulen und sehen sich Ihren Quellcode nicht an. Diese Personen würden es nützlich finden, diese Dokumentation in ihrem IDE, während sie ihren Code schreiben) verfügbar zu haben.

12
Thomas Owens

Der Wert eines Kommentars wird anhand des Werts der Informationen gemessen, die er enthält, abzüglich des Aufwands, der erforderlich ist, um ihn zu lesen und/oder zu ignorieren. Also, wenn wir den Kommentar analysieren

/// <summary>
/// Retrieves a product by its id, returns null if no product was found.
/// </summary>

für Wert und Kosten sehen wir drei Dinge:

  1. Retrieves a product by its id wiederholt, was der Name der Funktion sagt, also kostet es ohne Wert. Es sollte gelöscht werden.

  2. returns null if no product was found ist eine sehr wertvolle Information. Dies verkürzt wahrscheinlich die Zeit, die andere Codierer für die Implementierung der Funktion benötigen. Ich bin mir ziemlich sicher, dass es mehr Lesen spart als die Lesekosten, die es selbst verursacht. Es sollte bleiben.

  3. Die Linien

    /// <summary>
    /// </summary>
    

    tragen Sie keinerlei Informationen. Sie sind reine Kosten für den Leser des Kommentars. Sie können gerechtfertigt sein, wenn Ihr Dokumentationsgenerator sie benötigt. In diesem Fall sollten Sie jedoch wahrscheinlich über einen anderen Dokumentationsgenerator nachdenken.

    Dies ist der Grund, warum die Verwendung von Dokumentationsgeneratoren eine umstrittene Idee ist: Sie erfordern im Allgemeinen viele zusätzliche Kommentare, die keine Informationen enthalten oder offensichtliche Dinge wiederholen, nur um ein poliertes Dokument zu erhalten.


Eine Beobachtung, die ich in keiner der anderen Antworten gefunden habe:

Sogar Kommentare, die nicht notwendig sind, um den Code zu verstehen/zu verwenden, können sehr wertvoll sein. Hier ist ein solches Beispiel:

//XXX: The obvious way to do this would have been ...
//     However, since we need this functionality primarily for ...
//     doing this the non-obvious way of ...
//     gives us the advantage of ...

Wahrscheinlich viel Text, völlig unnötig, um den Code zu verstehen/zu verwenden. Es erklärt jedoch einen Grund, warum der Code so aussieht, wie er aussieht. Es wird die Leute davon abhalten, sich den Code anzusehen, sich fragen, warum dies nicht auf die offensichtliche Weise geschieht, und mit der Überarbeitung des Codes beginnen, bis sie erkennen, warum der Code überhaupt so geschrieben wurde. Und selbst wenn der Leser klug genug ist, nicht direkt zum Refactoring zu springen, muss er erst herausfinden, warum der Code so aussieht, wie er aussieht, bevor er erkennt, dass er am besten so bleiben sollte, wie er ist. Dieser Kommentar könnte buchstäblich Stunden Arbeit sparen. Somit ist der Wert höher als die Kosten.

Ebenso können Kommentare die Absichten eines Codes kommunizieren, anstatt nur, wie er funktioniert. Und sie können das Gesamtbild malen, das normalerweise im kleinsten Detail des Codes selbst verloren geht. Als solches sind Sie zu Recht für Klassenkommentare. Ich schätze Klassenkommentare am meisten, wenn sie die Absicht der Klasse erklären, wie sie mit anderen Klassen interagiert, wie sie verwendet werden soll usw. Leider bin ich kein großer Autor solcher Kommentare ...

Nicht kommentierter Code ist schlechter Code. Es ist ein weit verbreiteter (wenn nicht universeller) Mythos, dass Code auf die gleiche Weise gelesen werden kann wie beispielsweise Englisch. Es muss interpretiert werden und für jeden anderen als den trivialsten Code, der Zeit und Mühe kostet. Außerdem verfügt jeder über unterschiedliche Fähigkeiten zum Lesen und Schreiben einer bestimmten Sprache. Unterschiede zwischen den Codierungsstilen und -fähigkeiten des Autors und des Lesers sind starke Hindernisse für eine genaue Interpretation. Es ist auch ein Mythos, dass Sie die Absicht des Autors aus der Implementierung des Codes ableiten können. Nach meiner Erfahrung ist es selten falsch, zusätzliche Kommentare hinzuzufügen.

Robert Martin et al. Betrachten Sie es als "schlechten Geruch", da es sein kann, dass der Code geändert wird und die Kommentare nicht. Ich sage, es ist eine gute Sache (genauso wie dem Haushaltsgas ein "schlechter Geruch" hinzugefügt wird, um den Benutzer auf Undichtigkeiten aufmerksam zu machen). Das Lesen von Kommentaren bietet Ihnen einen nützlichen Ausgangspunkt für die Interpretation des tatsächlichen Codes. Wenn sie übereinstimmen, haben Sie mehr Vertrauen in den Code. Wenn sie sich unterscheiden, haben Sie einen Warngeruch festgestellt und müssen weitere Untersuchungen durchführen. Die Heilung eines "schlechten Geruchs" besteht nicht darin, den Geruch zu entfernen, sondern das Leck abzudichten.

4

In einigen Sprachen (z. B. F #) kann dieser gesamte Kommentar/die gesamte Dokumentation tatsächlich in der Methodensignatur ausgedrückt werden. Dies liegt daran, dass in F # null im Allgemeinen kein zulässiger Wert ist, es sei denn, dies ist ausdrücklich zulässig.

Was in F # (und auch in mehreren anderen funktionalen Sprachen) üblich ist, ist, dass Sie anstelle von null einen Optionstyp Option<T> Verwenden, der entweder None oder Some(T) sein kann. Die Sprache würde dies dann verstehen und Sie zwingen (oder Sie warnen, wenn Sie dies nicht tun), in beiden Fällen übereinzustimmen, wenn Sie versuchen, es zu verwenden.

So könnten Sie beispielsweise in F # eine Signatur haben, die so aussieht

val GetProductById: int -> Option<Product>

Und dann wäre dies eine Funktion, die einen Parameter (ein int) annimmt und dann entweder ein Produkt oder den Wert None zurückgibt.

Und dann könnten Sie es so verwenden

let product = GetProduct 42
match product with
| None -> printfn "No product found!"
| Some p -> DoThingWithProduct p

Und Sie würden Compiler-Warnungen erhalten, wenn Sie nicht mit beiden möglichen Fällen übereinstimmen. Es gibt also keine Möglichkeit, dort Nullreferenzausnahmen zu erhalten (es sei denn, Sie ignorieren natürlich die Compiler-Warnungen), und Sie wissen alles, was Sie brauchen, indem Sie sich nur die Funktionssignatur ansehen.

Dies setzt natürlich voraus, dass Ihre Sprache so gestaltet ist - was viele gängige Sprachen wie C #, Java, C++ usw. nicht sind. Dies ist für Sie in Ihrer aktuellen Situation möglicherweise nicht hilfreich. Aber es ist (hoffentlich) schön zu wissen, dass es Sprachen gibt, mit denen Sie diese Art von Informationen statisch typisieren können, ohne auf Kommentare usw. zurückgreifen zu müssen :)

3
wasatz

Hier gibt es einige ausgezeichnete Antworten, und ich möchte nicht wiederholen, was sie sagen. Aber lassen Sie mich ein paar Kommentare hinzufügen. (Kein Wortspiel beabsichtigt.)

Es gibt viele Aussagen, die kluge Leute machen - über Softwareentwicklung und viele andere Themen, nehme ich an -, die sehr gute Ratschläge sind, wenn sie im Kontext verstanden werden, die aber dumme Leute dann aus dem Kontext nehmen oder in unangemessenen Situationen anwenden oder anwenden lächerliche Extreme.

Die Idee, dass Code sich selbst dokumentieren sollte, ist eine solche hervorragende Idee. Im wirklichen Leben gibt es jedoch Einschränkungen hinsichtlich der Praktikabilität dieser Idee.

Ein Haken ist, dass die Sprache möglicherweise keine Funktionen bietet, um zu dokumentieren, was klar und präzise dokumentiert werden muss. Wenn sich die Computersprachen verbessern, wird dies immer weniger zum Problem. Aber ich glaube nicht, dass es vollständig verschwunden ist. Damals, als ich in Assembler schrieb, war es sehr sinnvoll, einen Kommentar wie "Gesamtpreis = Preis nicht steuerpflichtiger Gegenstände plus Preis steuerpflichtiger Gegenstände plus Preis steuerpflichtiger Gegenstände * Steuersatz" aufzunehmen. Was genau zu einem bestimmten Zeitpunkt in einem Register stand, war nicht unbedingt offensichtlich. Es waren viele Schritte erforderlich, um eine einfache Operation durchzuführen. Wenn Sie jedoch in einer modernen Sprache schreiben, ist ein solcher Kommentar nur eine Wiederholung einer Codezeile.

Ich ärgere mich immer, wenn ich Kommentare wie "x = x + 7; // 7 zu x hinzufügen" sehe. Wow, danke, wenn ich vergessen hätte, was ein Pluszeichen bedeutet, wäre das vielleicht sehr hilfreich gewesen. Ich könnte wirklich verwirrt sein, wenn ich weiß, was "x" ist oder warum es zu diesem bestimmten Zeitpunkt erforderlich war, 7 hinzuzufügen. Dieser Code kann selbstdokumentierend gemacht werden, indem "x" ein aussagekräftigerer Name gegeben wird und anstelle von 7 eine symbolische Konstante verwendet wird. Wenn Sie beispielsweise "total_price = total_price + MEMBERSHIP_FEE;" geschrieben haben, wird wahrscheinlich überhaupt kein Kommentar benötigt .

Es klingt gut zu sagen, dass ein Funktionsname Ihnen genau sagen sollte, was eine Funktion tut, damit zusätzliche Kommentare überflüssig werden. Ich habe gute Erinnerungen an die Zeit, als ich eine Funktion schrieb, die prüfte, ob sich eine Artikelnummer in unserer Datenbank-Artikeltabelle befand, die true oder false zurückgab und die ich "ValidateItemNumber" nannte. Schien wie ein anständiger Name. Dann kam jemand anderes und änderte diese Funktion, um auch eine Bestellung für den Artikel zu erstellen und die Datenbank zu aktualisieren, ohne den Namen zu ändern. Jetzt war der Name sehr irreführend. Es klang, als hätte es eine kleine Sache getan, als es wirklich viel mehr tat. Später nahm jemand sogar den Teil über die Validierung der Artikelnummer heraus und tat dies woanders, änderte aber den Namen immer noch nicht. Obwohl die Funktion nun nichts mehr mit der Validierung von Artikelnummern zu tun hatte, hieß sie dennoch ValidateItemNumber.

In der Praxis ist es jedoch oft unmöglich, dass ein Funktionsname vollständig beschreibt, was die Funktion tut, ohne dass der Name der Funktion so lang ist wie der Code, aus dem diese Funktion besteht. Wird uns der Name genau sagen, welche Validierungen für alle Parameter durchgeführt werden? Was passiert unter Ausnahmebedingungen? Jede mögliche Mehrdeutigkeit formulieren? Irgendwann würde der Name so lang werden, dass er nur noch verwirrend wird. Ich würde String BuildFullName (String Vorname, String Nachname) als anständige Funktionssignatur akzeptieren. Auch wenn dies nicht bedeutet, ob der Name "first last" oder "last, first" oder eine andere Variation ausgedrückt wird, was tut es, wenn einer oder beide Teile des Namens leer sind, wenn die kombinierte Länge und begrenzt werden Was macht es, wenn das überschritten wird, und Dutzende anderer Detailfragen, die man stellen könnte.

1
Jay