Kann auskommentierter Code eine wertvolle Dokumentation sein?

Ich habe folgenden Code geschrieben:

if (boutique == null) {
    boutique = new Boutique();

    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.persist(boutique);
} else {
    boutique.setSite(site);
    boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
    boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
    boutique.setNom(fluxBoutique.getNom());
    //boutique.setSelected(false);
    boutique.setIdWebSC(fluxBoutique.getId());
    boutique.setDateModification(new Date());

    boutiqueDao.merge(boutique);
}

Hier steht eine auskommentierte Zeile. Aber ich denke, es macht den Code klarer, indem es den Unterschied zwischen ifund deutlich macht else. Der Unterschied macht sich beim Hervorheben von Farben noch deutlicher bemerkbar.

Kann es eine gute Idee sein, Code wie diesen auszukommentieren?

Die meisten Antworten konzentrieren sich darauf, wie Sie diesen einen speziellen Fall umgestalten können. Lassen Sie mich jedoch eine allgemeine Antwort darauf geben, warum auskommentierter Code normalerweise schlecht ist:

Zunächst wird auskommentierter Code nicht kompiliert. Das ist offensichtlich, aber es bedeutet, dass:

1. Der Code funktioniert möglicherweise nicht einmal.

2. Wenn sich die Abhängigkeiten des Kommentars ändern, wird er nicht offensichtlich unterbrochen.

Kommentierter Code ist sehr viel "toter Code". Je länger es dort sitzt, desto mehr verrottet es und liefert dem nächsten Entwickler immer weniger Wert.

Zweitens ist der Zweck unklar. Sie brauchen wirklich einen längeren Kommentar, der den Kontext für zufällig kommentierte Zeilen liefert. Wenn ich nur eine kommentierte Codezeile sehe, muss ich untersuchen, wie sie dort ankommt, um zu verstehen, warum sie dort ankommt. Wer schrieb es? Was verpflichten? Was war die Commit-Nachricht / der Kontext? Und so weiter.

Überlegen Sie sich Alternativen:

• Wenn das Ziel darin besteht, Beispiele für die Verwendung einer Funktion / API bereitzustellen, führen Sie einen Komponententest durch. Unit-Tests sind realer Code und brechen ab, wenn sie nicht mehr korrekt sind.
• Verwenden Sie die Quellcodeverwaltung, wenn eine frühere Version des Codes beibehalten werden soll. Ich würde viel lieber eine frühere Version auschecken und dann die Kommentare in der gesamten Codebasis umschalten, um eine Änderung rückgängig zu machen.
• Wenn Sie eine alternative Version desselben Codes beibehalten möchten, verwenden Sie (erneut) die Quellcodeverwaltung. Dafür sind ja Branchen da.
• Überlegen Sie, wie Sie den Code umstrukturieren können, um die Struktur zu verdeutlichen. Die meisten anderen Antworten sind gute Beispiele dafür, wie Sie dies tun könnten.

Das größte Problem mit diesem Code ist, dass Sie diese 6 Zeilen dupliziert haben. Sobald Sie diese Verdoppelung beseitigen, ist dieser Kommentar unbrauchbar.

Wenn Sie eine boutiqueDao.mergeOrPersistMethode erstellen , können Sie diese folgendermaßen umschreiben:

if (boutique == null) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

boutiqueDao.mergeOrPersist(boutique);

Code, der ein bestimmtes Objekt erstellt oder aktualisiert, ist weit verbreitet. Sie sollten ihn also einmal lösen, indem Sie beispielsweise eine mergeOrPersistMethode erstellen . Sie sollten auf keinen Fall den gesamten Zuweisungscode für diese beiden Fälle duplizieren.

Viele ORMs haben dies auf irgendeine Weise unterstützt. Sie können beispielsweise eine neue Zeile erstellen, wenn der idWert null ist, und eine vorhandene Zeile aktualisieren, wenn der idWert nicht null ist. Die genaue Form hängt vom jeweiligen ORM ab, und da ich mit der von Ihnen verwendeten Technologie nicht vertraut bin, kann ich Ihnen dabei nicht helfen.

Wenn Sie keine mergeOrPersistMethode erstellen möchten , sollten Sie die Duplizierung auf andere Weise beseitigen, z. B. durch Einführung eines isNewBoutiqueFlags. Das mag nicht schön sein, aber es ist immer noch viel besser als die gesamte Zuweisungslogik zu duplizieren.

bool isNewBoutique = boutique == null;
if (isNewBoutique) {
    boutique = new Boutique();
    boutique.setSelected(false);
}

boutique.setSite(site);
boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getLogo());
boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE + fluxBoutique.getUrl());
boutique.setNom(fluxBoutique.getNom());
boutique.setIdWebSC(fluxBoutique.getId());
boutique.setDateModification(new Date());

if (isNewBoutique)
    boutiqueDao.persist(boutique);
else
    boutiqueDao.merge(boutique);

Dies ist eine absolut schreckliche Idee. Es wird nicht klar, was die Absicht ist. Hat der Entwickler die Zeile aus Versehen kommentiert? Um etwas zu testen? Was ist los?!

Abgesehen davon, dass ich 6 Zeilen sehe, die in beiden Fällen absolut gleich sind. Sie sollten diese Code-Duplizierung eher verhindern. Dann wird klarer, dass Sie in einem Fall zusätzlich setSelected aufrufen.

Nein, das ist eine schreckliche Idee. Ausgehend von diesem Teil des Codes fallen mir folgende Gedanken ein:

• Diese Zeile ist auskommentiert, weil der Entwickler das Debugging ausgeführt und vergessen hat, die Zeile in den vorherigen Zustand zurückzusetzen
• Diese Zeile ist auskommentiert, weil sie einmal Teil der Geschäftslogik war, aber nicht mehr der Fall ist
• Diese Zeile ist auskommentiert, da dies zu Leistungsproblemen in der Produktion führte und der Entwickler die Auswirkungen auf ein Produktionssystem untersuchen wollte

Nachdem ich Tausende von Zeilen auskommentierten Codes gesehen habe, mache ich jetzt das einzig Vernünftige, wenn ich es sehe: Ich entferne es sofort.

Es gibt keinen vernünftigen Grund, auskommentierten Code in ein Repository einzuchecken.

Außerdem wird in Ihrem Code viel dupliziert. Ich schlage vor, dass Sie dies so schnell wie möglich für die menschliche Lesbarkeit optimieren.

Ich möchte die Antwort von CodesInChaos nur ergänzen, indem ich darauf hinweise, dass Sie sie in kleine Methoden umwandeln können . Das gemeinsame Nutzen von Funktionen durch Komposition vermeidet die folgenden Bedingungen:

function fill(boutique) {    
  boutique.setSite(site);
  boutique.setUrlLogo(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getLogo());
  boutique.setUrlBoutique(CmsProperties.URL_FLUX_BOUTIQUE+fluxBoutique.getUrl());
  boutique.setNom(fluxBoutique.getNom());
  boutique.setIdWebSC(fluxBoutique.getId());
  boutique.setDateModification(new Date());
}    

function create() {
  boutique = new Boutique();      
  fill(boutique);
  boutique.setSelected(false);
  return boutiqueDao.persist(boutique);
}

function update(boutique) {
  fill(boutiquie);
  return boutiquieDao.merge(boutique); 
}

function createOrUpdate(boutique) {
  if (boutique == null) {
    return create();
  }
  return update(boutique);  
}

Obwohl dies eindeutig kein guter Fall für auskommentierten Code ist, gibt es eine Situation, die meines Erachtens dies rechtfertigt:

// The following code is obvious but does not work because of <x>
// <offending code>
<uglier answer that actually does work>

Es ist eine Warnung für jeden, der es später sieht, dass die offensichtliche Verbesserung nicht der Fall ist.

Edit: Ich spreche von etwas Kleinem. Wenn es groß ist, erklärst du es stattdessen.

In diesem speziellen Beispiel finde ich den auskommentierten Code sehr vieldeutig, hauptsächlich aus den in Dibkkes Antwort dargelegten Gründen . Andere haben Möglichkeiten vorgeschlagen, den Code zu überarbeiten, um der Versuchung zu entgehen, dies zu tun. Wenn dies jedoch aus irgendeinem Grund nicht möglich ist (z. B. sind die Zeilen ähnlich, aber nicht genau genug), würde ich einen Kommentar wie den folgenden begrüßen:

// Keine Notwendigkeit, diese Boutique abzuwählen, da [WHATEVER]

Ich denke jedoch, dass es einige Situationen gibt, in denen es nicht verwerflich ist, Code zu belassen (oder sogar auskommentierten Code hinzuzufügen). Wenn Sie etwas wie MATLAB oder NumPY verwenden, können Sie häufig äquivalenten Code schreiben, der entweder 1) über ein Array iteriert, jeweils ein Element verarbeitet oder 2) das gesamte Array auf einmal bearbeitet. In einigen Fällen ist Letzteres viel schneller, aber auch viel schwerer zu lesen. Wenn ich Code durch sein vektorisiertes Äquivalent ersetze, binde ich den Originalcode in einen Kommentar in der Nähe ein, wie folgt:

%% Der folgende vektorisierte Code führt dies aus:

% for ii in 1:N
%    for jj in 1:N
%      etc.

% aber die Matrix-Version läuft bei typischen Eingaben ca. 15x schneller (MK, 03.10.2013)

Natürlich muss man darauf achten, dass die beiden Versionen tatsächlich dasselbe tun und dass der Kommentar entweder mit dem tatsächlichen Code synchron bleibt oder entfernt wird, wenn sich der Code ändert. Natürlich gelten auch die üblichen Vorsichtsmaßnahmen zur vorzeitigen Optimierung ...

Das einzige Mal, dass ich auskommentierten Code gesehen habe, der nützlich war, war in Konfigurationsdateien, in denen der Code für jede Option angegeben, aber auskommentiert ist, um das Aktivieren von Einstellungen zu vereinfachen, indem nur Kommentarmarkierungen entfernt werden:

## Enable support for mouse input:
# enable_mouse = true

In diesem Fall hilft der auskommentierte Code, alle verfügbaren Optionen und deren Verwendung zu dokumentieren. Es ist auch üblich, die Standardwerte durchgehend zu verwenden, sodass der Code auch die Standardeinstellungen dokumentiert.

Im Allgemeinen ist Code nur für die Person selbstdokumentierend, die den Code geschrieben hat. Wenn Dokumentation erforderlich ist, schreiben Sie Dokumentation. Es ist nicht hinnehmbar zu erwarten, dass ein Entwickler, der neu in einer Quellcode-Basis ist, Tausende von Codezeilen liest, um herauszufinden, was auf hoher Ebene geschieht.

In diesem Fall besteht der Zweck der auskommentierten Codezeile darin, den Unterschied zwischen zwei Instanzen von doppeltem Code anzuzeigen. Anstatt zu versuchen, den Unterschied subtil mit einem Kommentar zu dokumentieren, schreiben Sie den Code neu, damit er Sinn ergibt. Wenn Sie dennoch der Meinung sind, dass ein Kommentar zum Code erforderlich ist, schreiben Sie einen entsprechenden Kommentar.

Nein, kommentierter Code wird veraltet und ist bald schlimmer als wertlos. Er ist häufig schädlich, da er einige Aspekte der Implementierung zusammen mit allen aktuellen Annahmen festlegt.

Kommentare sollten Schnittstellendetails und die beabsichtigte Funktion enthalten. "beabsichtigte Funktion": kann beinhalten, zuerst versuchen wir dies, dann versuchen wir das, dann scheitern wir auf diese Weise.

Die Programmierer, die ich gesehen habe, versuchen Dinge in Kommentaren zu belassen, sind einfach verliebt in das, was sie geschrieben haben, wollen es nicht verlieren, auch wenn es nichts zum fertigen Produkt hinzufügt.

Dies kann in sehr seltenen Fällen der Fall sein, aber nicht so, wie Sie es getan haben. Die anderen Antworten haben die Gründe dafür ziemlich gut herausgearbeitet.

Einer der seltenen Fälle ist eine Template- RPM-Spezifikation, die wir in meinem Shop als Ausgangspunkt für alle neuen Pakete verwenden, um sicherzustellen, dass nichts Wichtiges ausgelassen wird. Die meisten, aber nicht alle unserer Pakete haben einen Tarball, der Quellen enthält, die einen Standardnamen haben und mit einem Tag versehen sind:

Name:           foomatic
Version:        3.14
 ...
Source0:        %{name}-%{version}.tar.gz

Bei Paketen ohne Quellen kommentieren wir das Tag aus und setzen einen weiteren Kommentar darüber, um das Standardformat beizubehalten und darauf hinzuweisen, dass jemand das Problem im Rahmen des Entwicklungsprozesses gestoppt und bedacht hat:

Name:           barmatic
Version:        2.71
 ...
# This package has no sources.
# Source0:        %{name}-%{version}.tar.gz

Sie fügen keinen Code hinzu, von dem Sie wissen, dass er nicht verwendet wird, da er, wie andere bereits erwähnt haben, mit etwas verwechselt werden kann, das dorthin gehört. Es kann. Fügen Sie jedoch einen Kommentar hinzu, der erklärt, warum der erwartete Code fehlt:

if ( condition ) {
  foo();
  // Under most other circumstances, we would do a bar() here, but
  // we can't because the quux isn't activated yet.  We might call
  // bletch() later to rectify the situation.
  baz();
}

Auskommentierter Code wird von der Anwendung nicht verwendet, daher müssen weitere Kommentare hinzugefügt werden, aus denen hervorgeht, warum er nicht verwendet wird. In diesem Zusammenhang gibt es jedoch Situationen, in denen auskommentierter Code nützlich sein kann.

Was mir in den Sinn kommt, ist ein Fall, in dem Sie ein Problem mit einem gemeinsamen und ansprechenden Ansatz lösen, aber dann stellt sich heraus, dass die Anforderungen Ihres tatsächlichen Problems geringfügig von diesem Problem abweichen. Insbesondere wenn Ihre Anforderungen erheblich mehr Code erfordern, wird die Versuchung für die Betreuer, den Code mit dem alten Ansatz zu "optimieren", wahrscheinlich groß sein, aber dies wird nur den Fehler zurückbringen. Die "falsche" Implementierung in den Kommentaren beizubehalten, hilft, dies zu beseitigen, da Sie damit genau veranschaulichen können, warum dieser Ansatz in dieser Situation falsch ist.

Dies ist keine Situation, die ich mir sehr oft vorstellen kann. Normalerweise sollte es ausreichen, Dinge zu erklären, ohne ein Beispiel für eine "falsche" Implementierung aufzunehmen. Aber ich kann mir einen Fall vorstellen, in dem das nicht ausreicht. Da es sich also um die Frage handelt, ob es nützlich sein kann, ja, kann es. Nur nicht die meiste Zeit.

Das sieht nicht gut aus, Kumpel.

Kommentierter Code ist ... nur kein Code. Code ist für die Implementierung von Logik. Einen Code an sich lesbarer zu machen, ist eine Kunst. Wie @CodesInChaos bereits angedeutet hat, sind sich wiederholende Codezeilen keine sehr gute Implementierung der Logik .

Glauben Sie wirklich, dass ein echter Programmierer die Lesbarkeit der logischen Implementierung vorziehen wird? (Übrigens haben wir Kommentare und 'Ergänzungen', die wir in unsere logische Darstellung einfügen müssen).

Für mich sollte man einen Code für den Compiler schreiben, und das ist gut so - wenn 'es' diesen Code versteht. Für die menschliche Lesbarkeit Kommentare sind gut für die Entwickler (auf lange Sicht) und für Leute, die diesen Code wiederverwenden (z. B. Tester).

Ansonsten kann man hier etwas flexibleres ausprobieren, so etwas wie

boutique.setSite (site) kann durch ersetzt werden

setsiteof.boutique (Seite). Es gibt verschiedene Aspekte und Perspektiven von OOP, mit denen Sie die Lesbarkeit verbessern können.

Obwohl dieser Code auf den ersten Blick sehr ansprechend zu sein scheint und man denken kann, dass er einen Weg für die menschliche Lesbarkeit gefunden hat, während der Compiler auch seine Arbeit perfekt macht, und wir alle beginnen, dieser Praxis zu folgen, wird dies zu einer unscharfen Datei führen, die weniger lesbar wird in der Zeit und komplexer als es seinen Weg nach unten erweitern wird.