it-swarm.com.de

Menschen dazu zwingen, Code zu lesen und zu verstehen, anstatt Kommentare, Funktionszusammenfassungen und Debugger zu verwenden?

Ich bin ein junger Programmierer (abgeschlossene Informatikuniversität, aber noch weniger als ein Jahr in der Branche tätig) und habe kürzlich einen Job bei der Arbeit an C-Code für einen Webdienst mit anständiger Größe bekommen. Beim Betrachten des Codes sah ich nur Kommentare, wenn Leute ihren alten Code versteckten. Funktions- und Variablennamen sind die meiste Zeit ähnlich informativ - futex_up(&ws->g->conv_lock[conv->id%SPIN]);. Als ich einen erfahrenen Programmierer mit der Situation konfrontierte und erklärte, dass das Hinzufügen von Kommentaren und aussagekräftigen Namen den Code in Zukunft wartbarer und lesbarer machen würde, erhielt ich folgende Antwort:

Im Allgemeinen hasse ich Kommentare. Die meisten von ihnen verwenden, wie in dem Fall, den Sie mit dem Rückgabewert erwähnen, Kommentare, um das Lesen des Codes zu umgehen. Die Kommentare sagen nichts anderes aus als das, was der Typ zum Zeitpunkt des Einfügens des Kommentars (der oft vor seiner letzten Bearbeitung liegt) gedacht hat. Wenn Sie Kommentare eingeben, lesen die Leute den Code nicht so oft. Dann werden Fehler nicht erkannt und die Leute verstehen die Macken, Engpässe usw. des Systems nicht. Vorausgesetzt, die Kommentare werden tatsächlich mit Codeänderungen aktualisiert, was natürlich völlig ungarantiert ist.

Ich möchte die Leute zwingen, den Code zu lesen. Ich hasse Debugger aus einem ähnlichen Grund. Sie sind zu praktisch und ermöglichen es Ihnen, schmutzigen Code mit Uhren und Haltepunkten zu durchlaufen und das sogenannte Problem zu finden, wenn das eigentliche Problem darin bestand, dass der Code Fehler enthält, weil der Code nicht ausreichend vereinfacht wurde. Wenn wir den Debugger nicht hätten, würden wir uns weigern, hässlichen Code zu lesen und sagen, ich muss ihn bereinigen, damit ich sehen kann, was er tut. Wenn Sie mit dem Aufräumen fertig sind, verschwindet die Hälfte der Zeit.

Während das, was er schrieb, gegen vieles verstößt, was mir an der Universität beigebracht wurde, macht es doch Sinn. Da die Erfahrung in den Studien im wirklichen Leben manchmal nicht funktioniert, möchte ich eine Meinung von Leuten einholen, die mehr auf Code überprüft sind.

Ist der Ansatz, das Kommentieren von Code zu vermeiden, damit die Leute den Code tatsächlich lesen und verstehen, was in einer mittelgroßen Codierungsumgebung vor sich geht (eine, die von jeder Person, die innerhalb von ein oder zwei Monaten daran arbeitet, vernünftigerweise vollständig gelesen werden kann), sinnvoll? , oder ist es ein Rezept für eine langfristige Katastrophe? Was sind die Vor- und Nachteile des Ansatzes?

50
ThePiachu

Gut geschriebener Code sollte ausreichend selbstdokumentierend sein, sodass Sie keine Kommentare benötigen, die erklären , was der Code tut, da dies beim Lesen des Codes selbst offensichtlich ist . Dies impliziert auch, dass alle Funktionen und Variablen beschreibende Namen haben, obwohl dies möglicherweise erforderlich ist, um die Umgangssprache der Problem- und Lösungsdomänen zu lernen.

Dies bedeutet nicht, dass gut geschriebener Code vollständig ohne Kommentare sein sollte, da die wichtigen Kommentare diejenigen sind, die erklären , warum eine bestimmte, nicht triviale Funktion/block/etc ist so implementiert wie es ist und warum nicht eine andere Lösung gewählt wurde.

Das Problem bei Kommentaren, die den Code selbst beschreiben, besteht darin, dass sie tendenziell veraltet sind, da der Code geändert wird, um einen Fehler zu beheben, die Kommentare jedoch unberührt bleiben. Dies ist weitaus weniger der Fall bei Kommentaren, in denen die Gründe für die Erreichung der aktuellen Lösung beschrieben werden.

100

Jemand (zugeschrieben Richard C. Haven , ein Delphi-Programmierer) schrieb einmal:

  • Anfänger kommentieren nichts.

  • Gesellen kommentieren das Offensichtliche.

    myVar = myVar + 1; // add one to myVar
    
    /* This method adjusts the page margin by the appropriate device offset */
    
  • Meister kommentieren den Grund, warum sie es nicht anders machen

    /*
    
    I already tried obvious approaches A, B, and C to solve this problem.
    They didn't work for the following reasons: ...
    
    Therefore I wrote this less-than-obvious approach which works and 
    passes all unit tests.  
    
    */
    

Ihr "Senior-Programmierer" mag in Bezug auf Alter/Langlebigkeit Senior sein, aber es klingt für mich so, als hätte er ein professionelles Erwachsenwerden vor sich.


Was das Debuggen betrifft, gibt es viel zu sagen für sauberen Code und die liberale Verwendung von Protokollierung und/oder print() Anweisungen. Mit einem guten Debugger kann ich das Problem jedoch normalerweise in einem winzigen Bruchteil der Zeit finden, die es ohne ihn dauern würde. Es ist ein Elektrowerkzeug. Benutze es.

55
Dan Pichelman

Ich möchte die Leute zwingen, den Code zu lesen. Ich hasse Debugger aus einem ähnlichen Grund. Sie sind zu praktisch und ermöglichen es Ihnen, schmutzigen Code mit Uhren und Haltepunkten zu durchlaufen und das sogenannte Problem zu finden, wenn das eigentliche Problem darin bestand, dass der Code Fehler enthält, weil der Code nicht ausreichend vereinfacht wurde.

Ihr erfahrener Programmierer scheint ein verständliches Problem mit Codierungsstil zu haben. Er ist jedoch falsch darin, wie er das Problem angeht.

Beide Kommentare und beschreibende Codierung sind unerlässlich: Gut geschriebener Code mit beschreibenden Namen sagt Ihnen schnell, was Code tut ; Aber die Kommentare sagen dir, was der Code tun soll (und warum nicht, warum er es in eine Richtung tut und nicht eine andere . Dann haben Sie Unit-Tests, um zu überprüfen, ob der "Vertrag" (was der Code hätte tun sollen) tatsächlich erfüllt ist, und tun Sie dies automatisch, häufig und ohne weitere Anstrengung von Ihrer Seite.

Ohne die Kommentare würde es lange dauern (oder einen Komponententest, den Ihr Chef an dieser Stelle vermutlich noch weniger mag als Kommentare, wenn er glaubt, dass " Fehler von Leuten gefangen werden, die Code lesen =) bevor Sie den Fehler finden:

// Multiply margin by a fixed amount.
page->margin += fixedMargin;

und ja, der Kommentar könnte falsch sein, aber jetzt wissen Sie, dass in einer dieser beiden Zeilen ein Fehler vorliegt. Dies und eine weitere nützliche Ressource, die Versionskontrolle , ermöglichen es Ihnen, die Diskrepanz in weniger als 30 Sekunden zu finden. Wenn Sie die Ausgabe überprüfen und sogar mit einem Debugger fortfahren, ist dies möglicherweise nicht der Fall (ein Wert von fixedMargin von etwa 1,01 kann beispielsweise zu mehrdeutigen Ergebnissen führen).

Wenn Ihr Mentor nach Einfachheit strebt (ich stimme ihm zu, dass dies ein wünschenswertes Merkmal ist), sollte er eine Methode zur Überprüfung von Metriken wie zyklomatische Komplexität und zur Festlegung von Metrikzielen einsetzen. Das gilt auch für Kommentare: Ich stimme zu, dass es keinen Sinn macht, jede einzelne Codezeile zu dokumentieren, aber Sie sollten sich bemühen, Module, Funktionen und jeden "WTF-Punkt" im Code abzudecken.

// Useless comment: multiply a by four

// Useful comment (even if maybe it shouldn't be in this exact point of code):
// Zooming 2:1, four pixels get mapped into one, divisor needs multiplying by four
a *= 4;

Seine Methode kann zu Ergebnissen führen - falls er es hasst, hätten Sie 20% Codierung und 80% Dokumentation und Test. Mit seiner Methode erhalten Sie 20% Codierung und 80% Debugging und Head-Scratching.

Der Unterschied zwischen den beiden Fällen liegt meiner Meinung nach in der Moral und in der Gesamtproduktivität der Menschen. Wenn Sie Funktionen und Module ordnungsgemäß dokumentieren und verspotten, kann ein Modul von jemandem implementiert werden der das Gesamtbild nicht kennen muss, der die Nebenwirkungen in einem Black-Box-Szenario nicht untersuchen muss. und unter dem Strich kann weniger erfahren sein.

Ihr Mentor fühlt sich anscheinend wohl, wenn er eine furchterregende Menge von technische Schulden hochläuft. Ich würde seine Statistiken auf Terminverschiebungen und/oder ETAs überprüfen. Kurz gesagt, jedes langjährige Projekt, das nicht von einer Ein-Mann-Band oder einer eng verbundenen Gruppe von Coding-Freunden durchgeführt wird, muss früher oder später seine technische Schuld auf sich ziehen.

22
LSerni

Wenn Sie nur "den Code lesen" können, bekommen Sie keine Vorstellung davon, was die Funktion ist beabsichtigt. Wenn also jemand es versaut (ich weiß, dass es niemand tut, dies ist ein hypotetischer Fall) und etwas falsch macht, haben Sie keine Möglichkeit, es im Code zu überprüfen. Sie müssen auf Unit-Tests warten, um dies zu erkennen (wenn sie es überprüfen).

Hinzu kommt, dass ich ohne Hinzufügen von Kommentaren die Funktionen A1, A2, A3 ... von Anfang bis Ende lesen muss, während ich nur daran interessiert bin, die Funktion A zu verstehen, die alle oben genannten Funktionen aufruft.

Ich würde darauf wetten, dass Ihr älterer Programmierer faul (schlecht) ist oder möchte, dass die Leute bemerken, wie geschickt er codiert (viel schlimmer).

14
SJuan76

Wenn Sie Kommentare eingeben, lesen die Leute den Code nicht so oft. Dann werden Fehler nicht erkannt und die Leute verstehen die Macken, Engpässe usw. des Systems nicht. Vorausgesetzt, die Kommentare werden tatsächlich mit Codeänderungen aktualisiert, was natürlich völlig ungarantiert ist.

Nichts wie ein eigensinniger Idiot.

Das nächste Mal, wenn Sie ein Buch zum Lesen kaufen. Lesen Sie es unbedingt von vorne bis hinten, bevor Sie es kaufen. Andernfalls werden Sie nie genau wissen, ob es das ist, was Sie kaufen wollten. Das sagt er dir im Grunde.

Er hat einige Annahmen getroffen, die dumm sind.

  1. Wenn Sie den Quellcode lesen, erhalten Sie eine puristische Perspektive dessen, was er tut.
  2. Kommentare beziehen sich auf scope des Quellcodes, dem sie zugeordnet sind.

Das ist seine enge Perspektive in Bezug auf Kommentare, und als solche sieht er keinen Wert darin. Hier sind die Einschränkungen, keine Kommentare zu haben.

  1. Der Quellcode ist ein Befehlssatz für einen Computer. Es drückt keine Konzepte oder Ideen aus. Daher wird Ihnen der Quellcode niemals sagen, was die Programmiererziele waren. Quellcode, der fehlerfrei kompiliert wird und nicht abstürzt, kann die Ziele immer noch nicht erreichen. Woher wissen Sie, dass Sie sich vom Computer unterscheiden, indem Sie den Quellcode lesen? Der Computer tut dies bereits, kann jedoch das Ziel möglicherweise nicht erreichen.
  2. Der Quellcode erklärt nicht die Absicht des Programmierers. open window, Prompt for deposit erklärt nicht, dass der Programmierer beabsichtigte, dem Benutzer eine Warnung mitzuteilen.

Wenn Sie das nächste Mal ein Gespräch mit diesem Typen führen, fragt er Sie, warum Sie Ihrem Quellcode Kommentare hinzufügen. Antworte mit dieser Aussage.

"Ich schreibe Quellcode, um dem Computer zu sagen, was zu tun ist, und ich schreibe Kommentare, um den Leuten zu sagen, was zu tun ist."

7
Reactgular

Kommentare sollten als schriftliche Aufzeichnung verwendet werden, die etwas Verwirrendes erklärt. Wenn Sie etwas schreiben, das möglicherweise verwirrend ist und nicht vereinfacht werden kann, sodass Sie den Verdacht haben, dass es selbst Ihnen sechs Monate später schwer fällt, es zu verstehen, schreiben Sie einen Kommentar.

Wenn Sie alles und überall großzügig kommentieren, verlieren Kommentare ihre Wirksamkeit, um die Schwierigkeiten zu kennzeichnen. (Erinnere dich an die Fabel des Jungen, der "Wolf!" Rief)

Kommentare belegen "Bildschirmfläche", es sei denn, Sie haben einen guten Falteditor. Sie müssen sie immer wieder überspringen, wenn Sie sich im Code bewegen. Und natürlich Kommentare wie /* increment i by one */ neben an i++ sind kompletter Müll.

Wenn der Code so kompliziert ist, dass eine Anleitung zu den Interna erforderlich ist, schreiben Sie per Golly eine Anleitung zu den Interna. Nennen README-internals.txt (oder vielleicht HTML) und verstauen Sie es im selben Verzeichnis wie der Code und geben Sie einen Kommentar ein, der /* this is all explained in README-internals.txt */.

Über Debugger: Jedes Tool, mit dem Sie einen Fehler finden können, ist wertvoll. Es ist dumm, Werkzeuge zu verwerfen. Haltepunkt-Debugger sollten nicht verwendet werden, um zu überprüfen, ob der Code funktioniert. Zumindest nicht als primäres Mittel herangezogen. Ein Debugger wird fröhlich über eine Anweisung wie a[i] = i++ in C und bestätige eine schlechte Intuition.

Als Testwerkzeug kann man sich jedoch auf Debugging-Tools verlassen, die tatsächlich eine Art Laufzeitverletzung feststellen. Wenn Sie einen Debugger haben, der den Missbrauch des dynamischen Speichers abfängt, und der Code zahlreiche Testfälle unter diesem Debugger besteht, ist dies eine Quelle des Vertrauens, dass der Speicher nicht missbraucht wird.

Denken Sie also daran, dass sich "Debugger" auf mehr als eine Art von Tool bezieht, nicht nur auf einen Haltepunkt-/Schritt-Debugger. Einige Debugger bieten nur einen Einblick in das Programm, sodass Sie überlegen können, was falsch ist, während andere Debugger nach Problemen für Sie suchen.

Code kann nicht immer vereinfacht werden, um keinen Debugger zu haben oder die Verwendung zu verweigern. Was ist, wenn Sie dem Vorschlag Ihres Chefs folgen und den Code so vereinfachen, dass er nicht mehr weiter vereinfacht werden kann und Sie noch einen Debugger benötigen?

6
Kaz

Ich finde, dass die Codeüberprüfung ein fantastischer Prozess ist, um diese Frage auf konkrete Weise zu beantworten. Wenn ich die Pull-Anfrage von jemandem lese (indem ich mich wirklich bemühe, sie zu lesen, und sie nicht nur mit der Einstellung betrachte, dass alles sofort ersichtlich sein muss) und nicht verstehe, was sie tut, fordere ich die Leute auf, einen Kommentar hinzuzufügen. Oder Sie können dies selbst mit einer Gummiente tun.

Die meisten Leute wissen intuitiv, welche Ideen kommentiert werden müssen - es ist alles, was Sie jemandem sagen würden, der neben Ihnen steht, wenn er Ihnen eine Frage zum Code stellt. Oft werde ich jemanden bitten, etwas in einer Rezension zu erklären, er wird eine großartige Antwort geben, und meine Antwort lautet "Kopieren Sie diese Erklärung, die Sie gerade geschrieben haben, in einen Kommentar im Code."

Aber aus irgendeinem Grund ist dies selten der Inhalt, den die Leute am Ende in ihren Kommentaren schreiben. Stattdessen schreiben die Leute verrückte Sachen wie

/**
 * Gets the {@link List} of {@link Author}s for the given {@link Book}.
 *
 * @param book The {@link Book} for which you want the {@link Author}s.
 * @return All of the {@link Author}s for the given {@link Book}.
 */
List<Author> getAuthors(Book book) { ...

und

// increment i by 1
i += 1

und darauf reagieren die erfahrenen Mitarbeiter. Ich selbst sage den Leuten, wenn ich Code überprüfe, dass sie diese Art von Kommentaren auf niedriger Ebene entfernen sollen, die nicht mehr Informationen hinzufügen, als in den unmittelbar umgebenden Zeilen zu finden sind.

Ein Paradebeispiel für eine triviale Sache, die tut kommentiert werden muss, sind Beschreibungen von Ententypen in dynamischen Sprachen. Wenn das Argument oder der Rückgabewert einer Funktion ein Diktat mit einer Reihe von Eigenschaften ist, werden Sie später verrückt, wenn Sie nicht genau kommentieren, was diese Eigenschaften sind.

Keine Menge an Kommentaren bringt einen nicht trivialen Code auf das Niveau, das ein 8-Jähriger verstehen könnte. Sie sollten es also nicht versuchen. Sie müssen einige Annahmen treffen, dass der Leser weiß, wie man den Code liest, weil es sonst eine völlig vergebliche Anstrengung ist.

Schließlich sind Kommentare sehr oft falsch. Die Leute überspringen sie beim Lesen oft und aktualisieren sie nicht, wenn sich etwas ändert. Sie können keinen Komponententest für Ihre Kommentare schreiben. Daher ist nur die Möglichkeit, Ihren Code gegen die Fäulnis zu verteidigen, die auftritt, wenn Ihre nachlässigen Mitarbeiter damit anfangen, Affen zu spielen, darin, nur die Ideen zu kommentieren, die von entscheidender Bedeutung sind. Kommentare, die keinen Mehrwert bieten, fügen einen negativen Wert hinzu, wenn sie fehlerhaft werden.

Dokumentendesign, Ideen, Architektur, Geschichte, Begründung - keine Codezeilen.

5

In einer perfekten Welt ohne Fristen könnte sein Ansatz funktionieren.

Ein Benutzer hat einen Fehler in Anwendung X gemeldet. Wir lassen den neuen Mitarbeiter zwei Monate damit verbringen, ein tiefes und gründliches Verständnis des Codes zu erlangen, und fügen dann möglicherweise einige Wochen Refactoring hinzu. Wenn der Fehler weiterhin auftritt, sollte er ihn dann finden können und braucht nicht einmal einen Debugger!

In der realen Welt klingt dies nach einem zuverlässigen Weg, um aus dem Geschäft auszusteigen.

4
Heinzi

Beispiel für einen schlechten Kommentar

foo(); //calling function foo

Guter Kommentar

foo(); // must call function foo, because of a bug {link to bug}
4
Lukasz Madon

Code Complete, die wegweisende Arbeit zum Codierungsstil widmet der Frage der Kommentare mehrere Abschnitte (beginnend mit 19.3 in Ausgabe 1): die guten, die schlechten und die hässlichen. Daher sollten Sie und Ihr leitender Entwickler wahrscheinlich einen Blick darauf werfen.

Trotzdem sind gut geschriebene und gut platzierte Kommentare IMO für jedes große/langfristige Projekt sehr wichtig.

In einer perfekten Welt ist es wahr, dass Kommentare nicht wichtig wären. Aber wenn Sie kein fotografisches Gedächtnis haben und jeder, der an Ihrem Code arbeitet, ein Genie ist, helfen gute Kommentare nur, den Code so viel schneller zu verstehen, wenn Sie ein oder zwei Jahre später darauf zurückgreifen und ihn ändern müssen oder jemand anderes erbt dein Code. (Ich sage, dass dies 20 Jahre lang professionell gearbeitet hat und bis zu 5 oder 7 Jahre an einem Projekt mit mehreren anderen beteiligten Entwicklern)

Vor ein paar Jahren habe ich eine komplexe Anwendung geerbt, die die Arbeit erledigt, aber unter einer schlechten Architektur und einem inkonsistenten, aufgeblähten Codierungsstil leidet. Glücklicherweise ist der Code ziemlich gut kommentiert, was mir Tage und Wochen erspart hat, mich mit dieser Codebasis vertraut zu machen.

Eine andere Sache, die mir geholfen hat, mich auf den neuesten Stand zu bringen, war der von mir verwendete Debugger. Wenn ich eine neue Software analysiere, an der ich arbeiten muss, gehe ich als erstes alle Menüs durch, treffe ungültige oder seltsame Auswahlen und sehe nach, ob ich die App beschädigen kann. Wenn ich es kaputt mache, führe ich dieses Szenario mit dem Debugger aus und sehe, wohin mich dieser Fehler führt. Fast immer führt mich dies zu wichtigen Modulen und Knotenpunkten in der Codebasis: Ein schneller Weg, um die wichtigen Orte auf der Karte zu finden.

Obwohl ich mit meinem eigenen Code den Debugger im Allgemeinen nicht sehr oft verwenden muss, gibt es Fälle, in denen dies hilfreich ist - niemand ist perfekt, auch wenn er beim Testen von Einheiten akribisch ist (was oft unmöglich ist, wenn Sie eine enge Verbindung geerbt haben Legacy-Code.) Und wenn ich ein neues Modul oder eine neue Komponente verwende, hilft mir der Debugger, die Fehler und Missverständnisse, mit denen ich mich befassen muss, schnell zu finden, um mich mit den neuen Dingen vertraut zu machen.

Kurz gesagt: Zeit ist Geld, und die meisten von uns programmieren, um Produkte zu liefern und die Rechnungen zu bezahlen. Wochenlanges Sitzen durch Hunderte von Codezeilen, um einen Fehler zu finden, den der Debugger in 10 Sekunden aufdecken würde, oder schlecht geschriebener Code, der möglicherweise durch einige gute Kommentare beleuchtet wird, hilft Ihrem Endergebnis nicht sehr ...

Ihr leitender Entwickler ist anscheinend nicht an Effizienz interessiert und würde es vorziehen, wenn Entwickler Stunden und Tage damit verbringen, sich mit komplexem Code zu beschäftigen, wenn ein paar Kommentare den Tag retten würden. Gleiches gilt für seine Ideen zum Debuggen. (Nur neugierig: Verwendet der leitende Entwickler eine IDE? Warum nicht einfach alles in eine Textdatei eingeben und über die Befehlszeile usw. kompilieren und verknüpfen? Wie kann man jede einzelne Codezeile besser verstehen ...)

3
Vector

Die Kommentare sagen nichts anderes aus als das, was der Typ zu dem Zeitpunkt gedacht hat, als er den Kommentar eingegeben hat

Sie wissen, es ist ein äußerst theoretischer Ansatz. Ich wäre nicht überrascht, wenn es von einem theoretischen Mathematiker gesagt würde, aber in den Klängen eines erfahrenen Entwicklers klingt es nicht so, als wäre es jemand mit wirklich langer Übung.

Theoretisch können Sie den Code im Kopf analysieren, aber er funktioniert nur mit sehr einfachen Programmen. Bei komplexeren, realen Problemen stößt man auf Halteproblem , was eines der komplexesten Probleme in der Berechnungstheorie ist. Wenn jemand sagt, dass er Programme im Kopf analysieren kann, kann er wahrscheinlich eine RSA-Entschlüsselung im Speicher durchführen :)

Es scheint, als ob Ihr leitender Entwickler keine Erfahrung mit komplexen Problemen im wirklichen Leben hat oder versucht, Sie mit Tricks aus dem Film Hackers zu beeindrucken, oder er möchte seine eigene Faulheit rechtfertigen, wenn es darum geht, Kommentare zu schreiben.

2
Danubian Sailor

Ich schreibe jetzt seit ungefähr 40 Jahren Code und habe vielleicht etwas sehr Ähnliches gesagt wie dieser leitende Programmierer. Ich bin mir auch Wartungsprobleme sehr bewusst.

Trotzdem glaube ich, dass einige sehr wichtige Punkte in den obigen Antworten vergessen wurden:

Ich habe nit-Tests für den größten Teil meines Codes. Nicht wahr?

Das Warum der Funktionen (die Absicht hinter dem Code) wird normalerweise durch Tests ausgedrückt, und wenn Tests allein nicht ausreichen, werden sie kommentiert, manchmal sehr stark (wenn einige von Ihnen von Abfallprogrammierung gehört haben sie können verstehen, wovon ich spreche).

Die entgegengesetzten Kommentare in meinem Code sind sehr spärlich, fast nicht vorhanden, mit Ausnahme von zwei Sonderfällen: - Wenn das, was implementiert wird, einigen normativen Referenzen folgt (wie Implementierungen von Netzwerkprotokollen, woran ich gerade arbeite), setze ich normalerweise die Referenz als Kommentar über dem Code. - Ich verwende auch Kommentare, um zu vermeiden, dass der Programmierfluss unterbrochen wird. Ich füge Kommentare ein wie: dies oder das sieht falsch aus, behebe es später , wenn ich eine nicht verwandte Funktion codiere. Dies sind kurzfristige Kommentare (wie vom Programmierer definierte Warnungen), die später behoben werden sollten.

Mein Grund dafür ist, dass Kommentare im Code irreführend sein können. Sie können einen Kommentar leicht lesen und glauben, dass der Code das tut, was der Kommentar vorgibt, auch wenn er nicht wahr ist.

Wenn Kommentare zu Code in Tests sind, sind die Dinge anders. Es wird erklärt, wie Code aufgerufen werden soll und der Test sicherstellt, dass er dies tatsächlich tut.

Ich benutze normalerweise nicht viel Debugger. Ich behalte sie für einige Sonderfälle (meistens, wenn ich nicht verstehe, was der Code tut, wie seltsame Hardwarefehler).

Das hat sich mit der Zeit geändert. Vor 30 Jahren habe ich häufig Debugger verwendet. Was ich beobachtet habe ist, dass das Auffinden von Fehlern normalerweise viel langsamer ist als bei anderen Methoden. Was ich jetzt normalerweise mache, ist, Fehler in Unit-Tests zu lokalisieren, je früher desto besser. Dies hat den zusätzlichen Vorteil, einen Nicht-Regressionstest durchzuführen. Nie zweimal von demselben Käfer gebissen.

2
kriss

Kommentare sind für wer, wann, warum, Annahmen, Abhängigkeiten und möglicherweise wie.

Wer hat das geschrieben? Wen gehe ich und bug, wenn ich Fragen dazu habe?

Wann haben sie es geschrieben?

Warum haben sie es geschrieben? Was war der geschäftliche Grund, warum sie Zeit damit verbracht haben, Code zu schreiben?

Warum haben sie diesen Ansatz gewählt und welche anderen Ansätze haben sie abgelehnt und warum?

Welche Annahmen haben sie gemacht? Welche Überzeugungen über die Organisation hatten sie?

Welche Dinge müssen geschehen, damit dieser Code erfolgreich ausgeführt werden kann? Von welchen Bibliotheken, Objekten, Umgebungen oder anderen Dingen ist es abhängig?

In welchen Situationen kann der Code fehlschlagen und wie geht der Code mit diesen Fehlern um? Wie gehe ich mit ihnen um?

Was das "Wie" betrifft, sollten Kommentare nur erklären, wie der Code funktioniert, wenn er kompliziert und schwer zu verstehen ist (und wenn dies der Fall ist, hätte der Programmierer möglicherweise mehr Anstrengungen unternehmen müssen, um ihn zu vereinfachen).

2

Was Ihr leitender Entwickler meint, ist Code-Entropie. Ich stelle mir vor, er bezieht sich auf Fälle, in denen Code schlecht gestaltet ist, und der einzige Weg, ihn gut zu verstehen und damit zu arbeiten, sind Kommentare und Debugger.

Mit anderen Worten, Kommentare und Debugger können verwendet werden, um zugrunde liegende Probleme zu umgehen. Sie sind jedoch beide Werkzeuge, und die Schuld an dem Werkzeug ist kein effektiver Weg, um irgendetwas zu tun.

Wenn in Ihrem Beispiel eine Codebasis viel fehlerhaften Code enthält, besteht die Lösung nicht darin, Kommentare wegzulassen und alle dazu zu bringen, so viel Code wie möglich zu lesen. In der Tat ist dies eine Verschwendung von Zeit und Ressourcen. Richten Sie stattdessen Prozesse wie Peer Review und Pair Programming ein, bei denen der von einer Person geschriebene Code sicher von einer anderen Person überprüft wurde. Diese Prozesse erreichen nicht nur das gleiche Ziel mit besserer Genauigkeit, sondern vermeiden auch eine Verschwendung von Ressourcen, bei denen Dutzende von Entwicklern ein komplexes Stück Code verstehen müssen, nur weil es an Kommentaren und Dokumentation mangelt.

Darüber hinaus können effiziente Kommentare die Fehlermenge im Code reduzieren. Das Lesen erleichtert das Verständnis des Quellcodes und erspart Ihnen häufig das Durchsuchen ganzer Stapel von Quelldateien, um herauszufinden, warum eine Codezeile erforderlich ist. Sicher, der Kommentar kann sich als falsch herausstellen - aber wenn die Gesamtqualität des Projekts nicht geradezu schrecklich ist, sparen Sie am Ende mehr Zeit, wenn Sie genauen Kommentaren vertrauen, als wenn Sie gegen veraltete verlieren. Und Zeitersparnis beim Verstehen bedeutet mehr Zeit für das Refactoring, was eine viel bessere Möglichkeit ist, die Code-Entropie zu bekämpfen.

1
cib

Jedes Mal, wenn Sie Code schreiben, sollten Sie an den nächsten Programmierer denken, der das erbt, was Sie geschrieben haben. Wenn Sie Kommentare schreiben, weil Ihnen dies als bewährte Methode oder nur aus Gewohnheit beigebracht wurde, sollten Sie wahrscheinlich die ganze Zeit aufhören, Kommentare zu schreiben, da jeder, der Ihre Artikel liest, sie als nutzlos ignoriert.

Wenn Sie nur kommentieren, wenn Namenskonventionen und -strukturen ein seltsames Element Ihrer Arbeit nicht erklären können (normalerweise aufgrund von etwas anderem in einer Codebasis, das völlig durchgeknallt ist), werden sie das aufgreifen. Wenn Sie problematische Code-Teile markieren, geben Sie zum lauten Schreien ein Datum an, damit Sie Änderungen, die zu den Spielereien in der Quellcodeverwaltung geführt haben, leichter überprüfen können.

In Bezug auf Debugger kann ich einen Anflug von Solidarität mit dem (ich vermute) Old-School-Typ spüren, der hauptsächlich prozedural ist, weil ich von JavaScript komme, als alle IE sagten, dass Sie es waren) „Objekt nicht gefunden.“ Warum sie sich überhaupt die Mühe gemacht haben, weiß ich nicht, aber wenn Sie sich gelegentlich mit solchen Dingen befassen müssen, denken Sie viel schwerer darüber nach, wie Sie Ihren Code so strukturieren können, dass es ein wird viel offensichtlicher, wo etwas schief gelaufen ist, so dass Sie schnell mit Protokollierung/Warnungen diagnostizieren können.

Das heißt, ich würde Chrome Dev Tools oder Firebug nicht gegen etwas anderes als eine zeitreisende Polizeikiste eintauschen. Aber der Punkt, denke ich, ist dieser. Wenn das erste, was Sie tun, ist Starten Sie eine Ablaufverfolgung im Debugger, ohne sich den betreffenden Code anzusehen. Möglicherweise strukturieren Sie Ihren Code nicht so gut wie möglich. Versuchen Sie immer, so direkt und offensichtlich, minimalistisch und einfach zu lesen zu sein, als gäbe es kein IDE oder Debugger, um Ihnen zu helfen. Sehen Sie sich zunächst Ihren Code an, wenn Sie zuerst auf einen Haken stoßen. Wenn es nicht einfach ist, zu erraten, wo etwas schief geht, sollten Sie sich weitere Gedanken darüber machen, wie Sie vorgehen Ich würde Code ohne moderne Tools schreiben. Die meisten Java und C #, die ich je gesehen habe, haben keine Ahnung von den grundlegenden Grundlagen von OOP.

1
Erik Reppen

Früher habe ich viel kommentiert, jetzt sehr wenig. Den Code und die Variablennamen lesbar zu machen, ist der richtige Weg.
Ich füge Kommentare für echte 'Fallstricke' hinzu und 'warum dies getan wurde, ist (noch) nicht aus dem Code ersichtlich'.

Aber zu deiner WIRKLICHEN Frage.

Ich stelle fest, dass Ihr Titel mit dem Wort "Forcen" beginnt.

Ich stelle auch fest, dass im ersten Absatz "Konfrontation" erwähnt wird.

Ich habe vor 20 Jahren genau die gleichen Worte benutzt :)

Darum (IMHO natürlich) geht es beim Programmieren wirklich - wie verschiedene Menschen mit unterschiedlichen Stilen, Meinungen, Erfahrungen, Kenntnissen und Hintergründen zusammenarbeiten können.

Es gibt keine einfache Lösung, keine Liste programmatischer Schritte, keine einzige Konversation, um die Dinge in Ordnung zu bringen. Ich würde empfehlen, dass Sie über die folgenden Punkte nachdenken, die ich aus meiner 20-jährigen Erfahrung gelernt habe.

  1. Hör mal zu
  2. Hör mal zu
  3. Hör mal zu. Es tut mir leid, dass es so eine große Sache ist, aber nichts wird Ihnen in Ihrer Karriere mehr helfen, als Fragen zu stellen und zuzuhören, auch wenn die Antwort keinen Sinn ergibt.
  4. Stellen Sie Fragen und hören Sie sich die Antworten an, auch wenn Sie nicht einverstanden sind oder sie nicht vollständig verstehen. Es gibt fast immer eine zweite Chance, die Dinge noch einmal zu überdenken.
  5. Akzeptiere, dass manchmal Dinge erledigt werden. Wenn es sich wirklich um schlechte Entscheidungen handelt, die sich weiterhin zeigen, kann man später einen Fall vorbringen, um sie zu verbessern. Aber Betonung auf das Spätere. Gut genug für den Moment ist etwas, das Sie manchmal akzeptieren müssen, damit Sie vorerst mehr darüber erfahren können.
  6. Wählen Sie Ihre Schlachten auf Dinge, die falsch sind. Lerne, deine Zunge zu halten, es sei denn, der Gegenstand ist dir wirklich sehr wichtig und wähle deine Schlachten auch dann sehr sorgfältig aus - und versuche dann, Gespräche zu führen und keine Schlachten!
  7. Akzeptiere Unterschiede. Außerhalb der akademischen Welt müssen Sie mehr Unterschiede akzeptieren und sich ein wenig (weniger) darauf konzentrieren, die „richtige und wahre“ Art und Weise zu finden, Dinge zu tun, und mehr darauf, was für heute und für das Unternehmen, in dem Sie arbeiten, funktioniert.
  8. Vermeiden Sie Schwarz-Weiß-Gespräche. Seien Sie nicht absolutistisch in Bezug auf das Richtige. Vermeiden Sie absolutistische Wörter wie "Muss", "Nur", "Unmöglich" usw. und verwenden Sie Wörter wie "Sollte", "Oft" und "Schwer".
  9. Verwenden Sie konkrete Beispiele im Gespräch und nicht in der Theorie. Vermeiden Sie die Theorie nicht, aber versuchen Sie in Gesprächen, echte Beispiele für Ihre Punkte zu finden. Wenn Sie noch keine Beispiele aus der Praxis haben, kann dies ein Indikator dafür sein, dass Sie mehr als nur Gespräche auflisten sollten.
  10. Betonen Sie Ihre Jugend und Unwissenheit in Gesprächen mit erfahreneren Programmierern wie dem von Ihnen erwähnten. Sie werden sie mehr mit Demut beeindrucken als mit Ihrem kürzlich gewonnenen Wissen.
1
Michael Durrant

Kommentare werden sehr überbewertet und am häufigsten missbraucht. Obwohl ich nichts über Ihre aktuelle Situation weiß (da ich das zitierte Zitat nicht für eine gute Lesbarkeit des Codes finde), sollten Sie im Allgemeinen keine Kommentare über Ihren gesamten Code sprühen (mit Ausnahme von Kommentaren auf hoher Ebene) bereits in der Nähe von Dokumentation0.

Aus einem Grund ist das Kommentieren einer der Code-Gerüche, die im Martin Fowlers Refactoring-Buch beschrieben sind (eine Zusammenfassung finden Sie unter: http://www.industriallogic.com/wp-content/uploads/2005/09/smellstorefactorings) .pdf , das Buch ist afaik) nicht frei verfügbar.

Sie sollten jedoch Kommentare durch aussagekräftige Methoden- und Variablennamen ersetzen, und ich glaube nicht, dass w und gs klassifizieren. Persönlich würde ich jedoch mehr auf eine gute Benennung als auf Kommentare drängen.

Übrigens, wenn Sie nach "sauberem Code" und "Kommentaren" oder "Codegeruch" und "Kommentaren" suchen, finden Sie gute Lesungen darüber, dh. http://franksworld.com/blog/archive/2010/07/01/12035.aspx (mit einer Zusammenfassung, warum Onkel Bob Martin von Clean Code Kommentare nicht mag)

0
markijbema

Kommentare im Code sind ein Geschenk Gottes, wenn sie richtig verwendet werden, aber wie andere hier darauf hingewiesen haben, werden sie häufig überbeansprucht. Ich werde das, worauf bereits hingewiesen wurde, nicht wiederholen, aber ich werde sagen, dass Sie nur dann einen Kommentar abgeben sollten, wenn Sie wissen, dass der Code, den Sie schreiben, kompliziert ist und es keinen anderen praktikablen Weg gibt.

Wenn Sie das Gefühl haben, einen Kommentar abgeben zu müssen, denken Sie zuerst an den Code und fragen Sie sich. Warum schreibst du diesen Kommentar? Gibt es eine andere Möglichkeit, den Code zu schreiben, für die kein Kommentar erforderlich ist?

Schreiben Sie keine Kommentare, um Kommentare zu schreiben. Kommentieren Sie nur als letzten Ausweg oder wo es denjenigen hilft, die später an dem Code arbeiten müssen. Wenn Sie Kommentare schreiben, die beschreiben, was eine Variable tut, besteht die Möglichkeit, dass Sie zu viele Kommentare abgeben. Schlechte Programmierer kommentieren alles, gute Programmierer kommentieren nur bei Bedarf.

Beim Thema Debugger arbeite ich mit einigen Ingenieuren zusammen, die ihre gesamte Karriere hinter sich haben, ohne jemals einen Debugger gestartet zu haben. Warum? Ein Debugger ist ein Tool wie jedes andere. Genau wie in den meisten Fällen erledigt ein Kugelhammer die Arbeit, manchmal braucht man etwas mit mehr Finesse.

Ein Debugger dient zwei Zwecken.

  1. Es wird zum Auffinden von Fehlern verwendet
  2. Es zeigt einen Pfad durch Ihren Code.

Sie können sehr nützlich sein, um Neulinge auf den neuesten Stand zu bringen, und sie können noch nützlicher sein, um die sehr schwer zu findenden Fehler aufzuspüren, aber sie sind nicht der einzige Weg, und es gibt Zeiten, in denen ein Debugger tatsächlich eher ein Hindernis als eine Hilfe ist.

Was die Funktionszusammenfassung betrifft, sollte jede Funktion einen Docblock haben. Dies ist ein Muss, aber machen Sie sie nicht lang und ausführlich. Der Sommer sollte eine 1-zeilige Beschreibung sein, wobei jeder Parameter klar beschrieben wird.

/**
 * A getter method for foo
 *
 * @param bool $bar If true, bar will be attached to foo
 *
 * @return foo
 */

Verwenden Sie einen detaillierten Dokumentblock nur, wenn Grund dazu besteht. Wenn die Methode zu kompliziert ist, geben Sie eine Erklärung ein, aber wenn möglich, versuchen Sie, sie zu vermeiden. Guter Code sollte sich selbst dokumentieren.

Denken Sie daran, jeder liest gerne Romane, aber niemand möchte an einem Montagmorgen um 9 Uhr Krieg und Frieden lesen.

0
mplf