Sind mehr Kommentare in Umgebungen mit hohem Umsatz besser?

Ich habe heute mit einem Kollegen gesprochen. Wir arbeiten an Code für zwei verschiedene Projekte. In meinem Fall bin ich die einzige Person, die an meinem Code arbeitet. In ihrem Fall arbeiten mehrere Personen an derselben Codebasis, einschließlich Koop-Studenten, die ziemlich regelmäßig (zwischen 8 und 12 Monaten) kommen und gehen. Sie sagte, dass sie mit ihren Kommentaren liberal sei und sie überall hinbringe. Ihre Argumentation ist, dass es ihr hilft, sich daran zu erinnern, wo sich die Dinge befinden und was sie tun, da ein Großteil des Codes nicht von ihr geschrieben wurde und von jemand anderem als ihr geändert werden könnte. In der Zwischenzeit versuche ich, die Kommentare in meinem Code zu minimieren und sie nur an Stellen mit einer nicht offensichtlichen Problemumgehung oder einem Fehler einzufügen. Ich verstehe meinen Code jedoch insgesamt besser und habe eine direktere Kontrolle darüber.

Meine Meinung zu diesen Kommentaren sollte minimal sein und der Code sollte den größten Teil der Geschichte erzählen, aber ihre Argumentation macht auch Sinn. Gibt es irgendwelche Fehler in ihrer Argumentation? Es kann den Code überladen, aber es könnte letztendlich sehr hilfreich sein, wenn kurz- bis mittelfristig viele Leute daran arbeiten.

Kommentare überladen den Code nicht.

Und wenn doch, kann jede halbwegs anständige IDE Kommentare verbergen / falten. Idealerweise sollte die Geschichte durch Ihren Code, Ihr Anforderungsdokument, Ihren Commit-Verlauf und Ihre Komponententests und nicht durch Kommentare erzählt werden. Übermäßiges Kommentieren kann jedoch nur schaden, wenn sich die Kommentare auf das Wie und nicht auf das Warum konzentrieren. Dies ist jedoch eine andere Diskussion .

Ich denke, Sie und Ihre Kollegin haben "Recht", der Unterschied besteht natürlich darin, dass Sie alleine arbeiten und sie in einem Team, zu dem häufig unerfahrene Entwickler gehören. Sie haben nicht so sehr eine andere Philosophie in Bezug auf Kommentare, sondern ganz andere Anforderungen an die Kommunikation Ihres Codes. Das Argument "es hilft mir, mich zu erinnern" könnte auch auf die Tatsache zurückzuführen sein, dass sie sich mit viel mehr Code als Sie befasst und vor allem mit Code, der von verschiedenen Personen erstellt wurde, von denen jede ihre eigenen persönlichen Vorlieben und Macken hat.

Letztendlich sind Codekommentare, obwohl ihre offensichtlichen Mängel, die einfachste und schnellste Möglichkeit, Ihren Code zu kommunizieren. Abhängig von der Zusammensetzung und Organisation des Teams ist dies möglicherweise sogar der einzige Weg, der für den kleinsten gemeinsamen Nenner gilt. Normalerweise folge ich Ihrer Kommentarphilosophie, wenn ich alleine arbeite, und passe mich an die Ihres Kollegen an, wenn ich in einem Team arbeite, insbesondere wenn es sich um eine unausgewogene Teamfähigkeit handelt.

Erfolgreiche Kommentare in dieser Art von Umgebung vertuschen ein Problem, das auf andere Weise gelöst werden sollte.

Qualitativ hochwertiger, lesbarer Code sollte niemals zusätzliche Kommentare benötigen, um zu erklären, was er tut. Die einzige Zeit zum Kommentieren ist, wenn Sie erklären möchten, warum etwas auf eine bestimmte Weise getan wurde. Und selbst dann könnten diese Kommentare wohl in Commit-Nachrichten zur Quellcodeverwaltung enthalten sein.

Das Problem, das sie löst, ist, dass sie mit Schülern arbeiten muss, die nicht wissen, wie sie ihren Code lesbar schreiben sollen. Meiner Meinung nach ist es eine schwache Lösung für dieses Problem, den Code mit Kommentaren zu überladen.

Strenge Codeüberprüfungen wären viel effektiver, sowohl um den Code sauber zu halten als auch um die Schüler für die Zukunft zu verbessern, sei es im selben Unternehmen oder anderswo.

Das Problem mit Kommentaren ist, dass sie dazu neigen, sehr schnell nicht mehr mit dem Code synchron zu sein. Dies bedeutet, dass der Code häufig irreführende oder völlig falsche Kommentare enthält, sodass sie die Lesbarkeit mehr beeinträchtigen als helfen.

Ziel ist es, eine Codebasis leicht verständlich und modifizierbar zu machen. Sie können dies tun, indem Sie Kommentare großzügig verwenden (obwohl Sie möglicherweise auf das Problem der Datenkommentare stoßen), oder Sie können selbstdokumentierenden Code schreiben (so viel wie möglich) und nur Kommentare verwenden, um das nicht triviale "Warum" zu erklären " Fragen. Beide Ansätze könnten funktionieren, aber denken Sie daran, dass Sie zum Ändern des Codes den Code selbst und nicht nur die Kommentare verstehen müssen. Während Kommentare Ihnen helfen könnten, den Code zu verstehen, müssen Sie am Ende des Tages wahrscheinlich immer noch den Code selbst verstehen. Vor diesem Hintergrund bevorzuge ich den selbstdokumentierenden Code-Ansatz. Es scheint ein direkterer Weg zu sein, eine saubere Codebasis zu erstellen.

"Sind mehr Kommentare in Umgebungen mit hohem Umsatz besser?"

Ich denke, sie könnten schlimmer sein:

• Verschiedene Autoren verwenden unterschiedliche Stile und Detailebenen und sind weniger daran interessiert, Kommentare anderer Personen zu aktualisieren.

• Die Meinung von "Was muss kommentiert werden" ändert sich von Person zu Person.

• Sie setzen die Praxis fort, Code zu schreiben, der schwer zu lesen ist, mit Kommentaren, um ihn zu erklären, im Gegensatz zu einfach zu lesendem Code mit beschreibenden Namen.

• Die Beibehaltung ihres Formats und ihrer Konsistenz wird zu einer Aufgabe für sich.

• Neue Benutzer müssen den Formatierungsstandard kennen, bevor sie schnelle Änderungen vornehmen können.

Punkt 1: Klarheit ist in Umgebungen mit hohem Umsatz wichtig

Punkt 2: Ausführlichkeit ist keine Klarheit

Das Hinzufügen von Kommentaren zu Ihrem Code kann die Klarheit verbessern oder nicht. Dies hängt von den Kommentaren ab, die Sie hinzufügen. Und sobald die optimale Klarheit erreicht ist, werden zusätzliche Kommentare die Situation verschlechtern und nicht verbessern.

Während Kommentare eine Komponente der Klarheit sind, ist die Codequalität eine wesentlich wichtigere Komponente. Cleverness ist das Gegenteil von Klarheit . Wenn die Funktion des Codes durch gelegentliches Lesen nicht sofort ersichtlich ist, ist der Code nicht besonders klar, und Kommentare (egal wie hochwertig die Kommentare sind) sind ein schlechter und ineffektiver Ersatz für klaren Code.

Zum Beispiel kann das Einfügen eines Flags in das High-Bit eines nicht verwandten Feldes unter bestimmten Umständen durchaus zulässig sein, und unter bestimmten Umständen kann es aus Sicht der Leistung sehr sinnvoll sein, aber es ist in Bezug auf die Klarheit so gut wie immer eine schlechte Idee , auch wenn du es verdammt noch mal kommentierst.

Wenn Sie in der Prosa erklären müssen, was Ihr Code tut, sollten Sie Folgendes berücksichtigen: Beachten Sie, dass einige davon die Leistung beeinträchtigen können, die Leistung jedoch in bestimmten Fällen möglicherweise nicht so wichtig ist wie die Klarheit.

• Bessere Variablennamen und Funktionsnamen
• Besseres Codelayout und besserer Abstand
• Entfernen Sie alle "Tricks", die Sie für eine gute Idee hielten
• Gruppencode nach konzeptioneller Funktion (z. B. Code für einen bestimmten Zweck in eine entsprechend benannte Funktion extrahieren, auch wenn Sie ihn nur einmal aufrufen)
• Verwenden Sie einen einfacheren Algorithmus (sofern die Bedingungen dies zulassen).
• Verwenden Sie bekannte Bibliotheken für allgemeine Funktionen

Eine stark vereinfachte Antwort: "Je wahrscheinlicher es ist, dass Ihr Code erneut gelesen wird, desto höher ist die Belastung, zu erklären, was Sie tun." Dies erleichtert , indem der Code könnte lesen, indem sie sie zu kommentieren, durch formale Dokumentation der Erstellung von Normen folgende Stil ... Bitte beachten Sie, dass es könnte sein , Sie , die später die rereading tut, obwohl es sicherlich gilt auch für andere in einem ist Umfeld mit hohem Umsatz.

Es gibt einen weiteren großartigen Thread, der behandelt, ob Kommentare Dokumentation sind oder nicht.

Kommentare sind in einigen Szenarien hilfreicher als in anderen. Dies ist so grundlegend, dass ich mir Sorgen mache, wie ich es inmitten so vieler Antworten erklären soll, die ich als "Anti-Kommentar" empfinde.

Wenn Ihr Code möglicherweise jahrelang nicht gelesen wird, sind Kommentare wichtiger als bei häufigem Code-Refactoring, starkem Code-Besitz und umfangreichen Code-Überprüfungen. Wenn Ihre Anwendung komplex ist und Techniken verwendet, die für einen Beobachter, der diese Sprache beherrscht, nicht sofort offensichtlich sind , sind Kommentare wichtiger als wenn das System eine verherrlichte "Hallo Welt" ist. Wenn die Codebasis nicht so streng mit Standards ist, wie es sein könnte, sind Kommentare wichtiger als wenn Sie mit sechs Ebenen der Qualitätssicherung arbeiten. Wenn Sie in einem Team mit acht Personen arbeiten, die gerade die Sprache lernen, sind Kommentare wichtiger als wenn Ihr Team über acht programmierende Pulitzer verfügt. Wenn Sie eine weitläufige Anwendung in Ihrem Schoß haben,Kommentare sind wichtiger, als wenn Sie es sauber von Grund auf neu erstellen könnten.

Wäre es in den meisten dieser Szenarien besser, die zugrunde liegende Ursache zu beheben, als die Verwendung von Kommentaren zu erhöhen? Absolut. Aber manchmal stecken Sie in einer Codebasis fest, auf der mehr Fingerabdrücke als auf dem Stadt-Smartphone gespeichert sind. Der beste Weg, dies zu verbessern, besteht darin, Ihre Änderungen so lesbar wie möglich zu machen und sie zum Teufel zu kommentieren.

Zu Ihrem spezifischen Problem: Kommentare sollten nicht so weit verstreut sein, dass der Code unübersichtlich wird. Ein gut geschriebener Absatz am Anfang einer Unterroutine, der beschreibt, warum eine Funktion existiert und warum sie diesen Ansatz verwendet, ist oft die beste Wahl, um dem nächsten Programmierer zu helfen, sich zu orientieren.