Was ist das goldene Code / Kommentar Verhältnis? [geschlossen]

https://stackoverflow.com/questions/111563

02-07-2019
|

Frage

Sie haben ein Code / Kommentar-Verhältnis, die Sie als ein Zeichen der guten (sehr schlecht) Code Gesundheit sein?

Können Sie Beispiele für Open-Source-Projekte geben, die als gut codiert werden und ihr jeweiliges Kommentar Verhältnis?

(Ich weiß, dass kein Verhältnis für jedes Projekt „true“ ist, und es kann sehr gut crappy Projekte, die dieses theoretische goldene Verhältnis aufweisen. Trotzdem ...)

Lösung

Kommentare sollten sehr selten und wertvoll sein, fast immer Ausdruck die „Warum“ und nie die „Wie“ (die Ausnahme ist, wenn der, wie komplex und nicht leicht erkennbar aus dem Code).

Jeder Kommentar ist ein Hinweis, dass Sie möglicherweise Refactoring den Code der Absicht klarer zu machen. Jeder Kommentar Risiken so schnell veralten, wie es geschrieben ist.

Wir haben fast keine Kommentare abgesehen von XML-Kommentare in unserem xUnit.net Projekt , aber einige Leute den Code klar und leicht zu lesen scheinen zu finden. :)

Andere Tipps

Wer hat Code von einem anderen Programmierer zu beheben sagen so viele Kommentare wie möglich . Das große Problem mit altem Code ist: „.. Sie sehen, was der Code machen Sie sehen, dass dies das Problem ist, aber man weiß nicht, warum die Programmierer es so schrieben“

Um einen Fehler zu verstehen, was Sie wissen müssen:

was sollte der Code tun (nicht was der Code tut) und warum.
Der Vertrag von jeder Funktion. Wenn zum Beispiel ein Nullpointer dann, wo ist der Fehler? In der Funktion oder in der aufrufenden Funktion?
Auf jedem Hack ist beschrieben, wie das Problem (Sprachversion, OS, OS-Version) wiedergegeben werden kann. Zum Beispiel haben wir viele Hacks für eine alte Java VM, die nicht mehr unterstützt wird. Aber wir sind nicht sicher, ob wir es entfernen, weil wir nicht wissen, wie sie zu reproduzieren.

Wir haben ein Verhältnis von 2-3%, was zu wenig ist. Ich denke, dass 10% für große oder lange gelebt Projekte gut ist.

Leider ist es nicht Faustregel. Frameworks und Bibliotheken, pro Instanz, erfordert viel mehr Kommentare, weil Programmierer Kunden sein und haben keine Zeit, Code, den sie jedes Mal zu lesen brauchen eine Methode aufzurufen.

Projekte, wo Sie schreiben / lesen Code weniger Kommentare benötigt und sollten versuchen, die Lesbarkeit des Codes statt Kommentar / Code-Verhältnis zu verbessern.

Mit freundlichen Grüßen

Kommentare erklären nicht nur den Code -. Sie auch den Debugger führen, die für das Stück Code sucht, die etwas tut,

Abrufen eines Kunden Auftragshistorie oder Berechnung, ob ein Feind Spieler sichtbar ist Dutzende von Codezeilen in Anspruch nehmen, und selbst ein erfahrener Programmierer kann einige Minuten dauern, um sicherzustellen, dass das, was sie tut. Ein Kommentar, der sagt, kann der Debugger „die Auftragshistorie des Kunden abrufen“, um nicht zu, dass Code untersuchen, wenn er weiß, dass die Reihenfolge der Geschichte ist nicht das Problem.

ich kommentieren alles, was ich glaube, nicht eindeutig ist, oder sollte erklärt werden. Oft ich über Kommentar. Warum? Weil Sie nie wissen, wer auf Ihrem Code arbeiten. Ich mag eine Situation vorzustellen, in der sie den halben Mannschaft mit Affen ersetzen, die nur verstehen, dass, wenn sie auf einer Zeile eingeben drücken, sie eine Banane bekommen. Also, wenn sie zumindest lesen lernen, werden sie nicht meine Logik ändern, ohne zuerst die Kommentare zu lesen.

Case und Punkt:

// Delete the helloworld file
exec("rm -f helloworld.txt")

Bekomme nicht geändert:

exec("rm -rf /")

Unwahrscheinlich, ich weiß, aber auch einig gut Entwickler sind bekannt Logik zu ändern, weil es sieht nicht richtig aus und nicht, weil es ein Fehler war, oder Anforderungsänderung .

Ich denke, jeder kann sich einig, dass 0 Kommentare können in der Regel Unter dokumentiert Code in Betracht gezogen werden. Denken Sie daran, dass auch der Code selbstdokumentiere immer nur nachweisen kann, was ist es ; nie, was absichtlich weggelassen, wegoptimiert wurde, versucht und verworfen, usw. Sie werden immer eine Notwendigkeit für Englisch haben, im Grunde in die Quelldateien, oder Sie sind verpflichtet, wichtige Einschränkungen und Design-Entscheidungen auszulassen.

Ich bin daran interessiert, wie diese soliden Prinzipien ihr befürworten sind (mit denen ich in voller Übereinstimmung bin bisher) in Code Statistiken übersetzen. Insbesondere was sind Open-Source-Projekte als gut sein (nicht über) dokumentiert, und was ist der Kommentar Verhältnis gibt.

Ich habe eine sehr einfache Regel-of-Daumen: Wenn Sie anhalten müssen und denken mehr als ~ 15 Sekunden, wenn einige Stück Code Codierung (sagen wir, eine Funktion oder eine komplexe Schleife, etc.), dann das Stück Code braucht einen Kommentar.

Es funktioniert wirklich gut für mich. Nächstes Mal, wenn Sie oder jemand in Ihrem Maß an Verständnis für die Gesamtcodebasis, läuft in diesem Stück Code, (e) er wird sofort sehen, Warum wurde es die Art und Weise getan, um es getan hat.

LOC / LOcomment = yearsofexp / 5

Meine Regel ist: Wenn es etwas gibt, was gesagt werden muss und der Code können nicht gemacht werden, um es auszudrücken, dann können Sie einen Kommentar schreiben. Andernfalls, wenn der Code können drücken die Idee, dann müssen Sie die Idee in den Code oder seine Tests auszudrücken.

Wenn Sie diese Regel befolgen, dann sollten Sie den Code nur Kommentare muß, wenn es mit einigem inobvious Problem in der Hardware oder Betriebssystem zu tun, oder wenn der naheliegendste Algorithmus ist nicht die beste Wahl. Dies sind: „Das ist komisch, weil“ Kommentare, und wirklich sind nur Bewältigungs mechanism.Most der Zeit Kommentare im Code sind wirklich nur Entschuldigungen für nicht in einer offensichtlichen Art und Weise zu schreiben, und solche Kommentare vermieden werden sollten und dann gelöscht.

Auch die guten Kommentare werden oft Lügen im Laufe der Zeit, so dass Informationen in nicht-ausführbar, nicht testbare Orten wie Kommentare mit Verdacht zu beäugte sind. Auch hier ist die Antwort auf ersten Kommentar zu vermeiden, dann löschen Sie es.

Mein ideales Verhältnis ist gleich Null. Allerdings ist die Welt weniger als ideal, so dass ich Kommentare akzeptieren, wenn es keine andere Möglichkeit ist eine wichtige Idee zu kommunizieren.

sollte es Kommentare dort, wo man sie für notwendig halten. Nicht mehr und nicht weniger.

die Teile anmerken, dass Sie denken, Sie könnten nicht verstehen, nach 6+ Wochen Pause bei der Suche wieder auf dem Code

Ich versuche, Kommentare zu einem Minimum zu halten. Code sollte selbst explainetory sein und während Quellcode neigt bleiben als falsch explaination hinter fast immer die Kommentare zu ändern.

Das goldene Code / Kommentar-Verhältnis ist der Schnittpunkt von

Kommentare erforderlich, sich der Dinge zu erinnern, die Sie im Auge hatte, während Codierung
Kommentare benötigten andere Dinge zu erinnern, die Sie im Auge hatten, während Codierung
Kommentare Ihr Kunde bereit ist, für (weil gute Kommentare Kosten Zeit)
die Interesse der Entwickler in verschleierten Code produzieren, weil die Arbeitssicherheit (wenn er oder sie arbeitet für ein Unternehmen, in dem ein Entwickler mit ihm weg bekommen kann)

Dies zeigt auch, warum das Verhältnis für jedes Projekt ist anders und jedes Team.

Es gibt kein goldenes Verhältnis. Die Anzahl der Kommentare hängt stark von der inhärenten Komplexität des Codes. Wenn Sie nur CRUD-Anwendungen zu schreiben, müssen Sie wahrscheinlich nicht viele Kommentare. Wenn Sie ein Betriebssystem oder ein RDBMS schreiben, müssen Sie wahrscheinlich mehr kommentieren, wie Sie kompliziertere Codierung tun werden und müssen, um es ein wenig deutlicher, warum Sie die Dinge tun Sie tun.

Wenn Sie einige Daten der realen Welt auf Kommentar-Verhältnisse für verschiedene Sprachen wollen, werfen Sie einen Blick auf Ohloo .

Als Beispiel können Sie bei der Suche verschiedene Metriken für die Linux-Kernel-Quelle.

Ich glaube nicht, dass jemand können Sie Zahlen nennen, aber es sollte als in der Quelle in die Header-Dateien weit höher sein.

Ich würde die Header-Datei für eine Klasse erwartet alle Klassen / Funktionen zu dokumentieren / etc öffentlich zugänglich durch diese Header-Datei enthält. Das kann eine ganze Reihe von Linien, eine Funktion, dessen Prototyp zu dokumentieren ist eine einzige Zeile (nein, nur gute Namen für Funktionen auswählen und deren Parameter ist nicht genug - es kann sein, aber oft nicht ist). Drei Linien des Kommentars für jede Codezeile nicht zu groß werden.

Für eigentlichen Code, wäre es viel niedriger sein. Ich bin nicht mit dem Extremisten zustimmen, die Sie denken sollen für null Kommentare zielen darauf ab, aber sicherlich, wenn Sie denken, dass Sie Kommentare benötigen sollten Sie zunächst prüfen, ob der Code klarer gemacht werden.

Es kann durchaus ein wenig variieren. Zum Beispiel können Sie Code haben so gut geschrieben, dass die Kommentare wären nur eine Verschwendung von Zeit.

Sie müssen genügend Kommentare so Monate später Sie in Ihrem Code aussehen kann, lesen Sie den Kommentar und wählen Sie einfach, wo Sie aufgehört haben, ohne viel Aufwand. Wenn die Lebensgeschichte des Codes nicht erforderlich ist, kann es nicht schreiben.

Es gibt nicht so etwas wie einen guten Kommentar Code Verhältnis. In den alten Zeiten glaubten einige Leute, dass Sie einen Kommentar an der Spitze jeder Funktion benötigt, um zu erklären, was es tut.

Doch mit dem Aufkommen der modernen Sprachen Code ziemlich selbstdokumentiere. Dies bedeutet, dass die einzigen Gründe, einen Kommentar im Code setzen links ist entweder zu erklären, wo ein oddball Entscheidung kam aus oder mit dem Verständnis ein wirklich kompliziertes Thema zu helfen.

Es gibt keinen „goldenen Schnitt“. Es hängt von der Sprache und die Art und Weise, dass Sie es schreiben. Der ausdruck Code, desto mehr können sie selbsterklärend sein - und damit auch die weniger Kommentare, die Sie benötigen. Das ist ein Vorteil, fließend Schnittstellen.

Sie können einen festen Code / Bemerkungen Verhältnis Mandat sonst Sie mit Code beenden mit Lärm geschnürt wie:

// Add one to i
i++;

die Wolken nur den Code.

aussehen Statt an der Komplexität des Codes und sehen, was Sie erklären müssen, das heißt squirelly Logik, warum bestimmte magische Zahlen verwendet werden, welche Annahmen bezüglich vorhanden sind eingehende Formate etc.

Schalten Sie das Maintainer Denken und denken, was Sie in Bezug auf den Code beschrieben sehen möchten Sie gerade geschrieben haben.

HTH.

prost,

Rob

Kommentare haben 3 Anwendungen, IMO:

Erklären Sie Warum der Code tut, was es tut
Dokumentieren Sie die Schnittstelle für ein Modul
warum andere Ansätze zu einem Stück der Logik nicht genommen wurden

Wenn der Code etwas Grundsätzliches genug zu tun, dass die Warum ist klar, das die meiste Zeit in den meisten Bereichen sein sollte, dann sind die Kommentare innerhalb der Logik sollte minimal sein ... auch keine Annäherung . Kommentare sollten nie die werden zu erklären, was (mit möglichen Ausnahmen zum Beispiel zu sagen, dass die Funktion eine Implementierung des Foo-Algorithmus ist wie in Bar-Veröffentlichung erklärt). Wenn Sie erklären müssen was du tust, bist du es schlecht zu tun.

Es gibt eine ausgezeichnete Diskussion von Code-Kommentaren in Steve McConnells () Buch Code Complete (ich habe die erste Ausgabe, aber ich glaube, ist jetzt eine zweite Auflage link text )

Insgesamt stärkt es das, was die anderen Antworten erwähnt - sollten selten und beschreiben sein die, warum nicht die, wie - wenn Sie Variable und Methodennamen Refactoring Kommentare ersetzen dann das prefferred werden sollte - mit den meisten IDE eine Art von Intellisense bietet ( oder wie ich einmal gehört Don Box beschreiben es als - intellicrack aufgrund seiner adictivness) gibt es keinen Grund Variable / Methodennamen zu kürzen, wenn eine längere bessere Version seiner Absicht deutlicher kommunizieren würde

0/0 ; zero divided by zero
Runtime error (func=(main), adr=3): Divide by zero

ein implizites "Do What I Mean" Befehl mit einem "kein Kommentar" kommentieren?

Es gibt kein solches Verhältnis.

In der Regel sollen, Kommentare nur dort in Situationen, in denen etwas könnte wirklich unklar sein, wie

// Do not Dispose!
SPSite site = properties.Feature.Parent as SPSite;

Auf der anderen Seite, wenn Sie Code jemand verkaufen, müssen sie so viele Kommentare wie möglich. Imaging Verkauf eine 3D-Engine oder eine andere Spiel Middleware, die keine Kommentare. Sicher, API-Dokumentation usw. ist ein großer Teil dieser Middleware als gut, aber gut kommentierten Code als auch auszahlt. Sachen wie „1 bis i“ ist noch zu spammy, aber so etwas wie „Create () wird zunächst prüfen, ob DirectX 10 zur Verfügung steht und fällt zurück auf das Gerät DirectX 9, wenn es nicht“, kann sehr hilfreich sein, auch wenn es trivial zu sieht aus dem Code.

Im Allgemeinen ist interner Code in der Regel viel weniger als kommentierte Code, den Sie verkaufen, aber Ausnahmen gelten.

Ich mag kommentieren verwenden, um Code zu annotieren, dass ich sicher, ist leicht zu lesen und informativ Variablen hat. Davon abgesehen, Ich mag jede Codezeile, um zu versuchen zu schreiben, wie informativ als Kommentar, wenn möglich. Sie sollten einen sehr starken Kern zu haben, fähig sein, was der Code ist, bevor Sie die Kommentare lesen, oder Sie tun es falsch.

3% bis 9,5%, mehr oder weniger

Ich muss sagen, dass ich hier bin um 2 Kommentare pro 1 Zeile Code nach einer Antwort suchen. Auch wenn dies eine Übertreibung ist es in der richtigen Richtung! Stattdessen sehe ich Leute empfehlen Kommentare wie Trüffel oder andere seltene Ware zu behandeln. Blickt man von einer besonderen Perspektive der Wissenschaft, waren die Codequalität ist gering und die Verwendung von Versionskontrolle ist noch seltener dann Trüffel würde ich niemanden drängen, so viel wie möglich Kommentare zu schreiben, auch gegen die eigene Beurteilung, ob der Kommentar ist zu 100% notwendig.

Kommentare machen Ihnen das Leben leichter, weil die Chancen sind Sie zu gehen, zu denken, was zum Teufel dachte ich, wenn dieses Schreiben!

Lizenziert unter: CC-BY-SA mit Zuschreibung

Nicht verbunden mit StackOverflow