Denken Sie, dass Code selbstdokumentierend ist? [geschlossen]

Dies ist eine Frage, die mir vor vielen Jahren als Absolvent in einem Vorstellungsgespräch gestellt wurde und die ab und zu in meinem Gehirn zermürbt und bei der ich nie wirklich eine gute Antwort gefunden habe, die mich zufrieden stellte.

Der fragliche Interviewer suchte nach einer Schwarz-Weiß-Antwort, es gab keinen Mittelweg. Ich habe nie die Gelegenheit gehabt, nach den Hintergründen der Frage zu fragen, aber ich bin gespannt, warum diese Frage einem Entwickler gestellt wird und was Sie aus einer Ja- oder Nein-Antwort lernen würden.

Aus meiner Sicht kann ich Java, Python, Delphi usw. lesen, aber wenn mein Manager zu mir kommt und mich fragt, wie weit ich in einem Projekt bin, sage ich "Der Code ist zu 80% vollständig" (und früher) Wenn Sie anfangen, mich niederzuschießen, habe ich gehört, dass dies in einigen Büros von Entwicklern geäußert wurde. Entschuldigung, wenn diese Frage seltsam erscheint, aber ich möchte lieber nachfragen und ein paar Meinungen dazu einholen, um ein besseres Verständnis dafür zu erlangen, warum sie in einem Interview an jemanden weitergegeben wird.

Teilweise.

Code, der große englische Wörter verwendet, kann sich teilweise selbst dokumentieren, da die Namen aller Funktionen und Variablen Aufschluss darüber geben, was er tut. Aber es wird dir wahrscheinlich nicht sagen warum.

Vergleichen Sie:

a->b;
# what is b doing? what is the a object?

carEngine->startIgnition;
# much more clear what objects are involved

Aber Sie wissen immer noch nicht, warum ein Auto gestartet wird. Daher nur teilweise. Es ist ein bisschen schrecklich, dass Ihr Interviewer eine Schwarz-Weiß-Antwort erwartet hat, es sei denn, seine Sichtweise auf Schwarz-Weiß enthielt möglicherweise eine sehr starke.

Code an sich ist nicht selbstdokumentierend.

Der Grund ist, dass der Code das WIE angibt und sich nicht um das WARUM kümmert, was die Menschen wissen müssen, um den Code zu pflegen.

Daher benötigen Sie zusätzliche Kommentare, in denen alle WARUM - Punkte erläutert werden . Sie können sie einschränken, indem Sie zulassen, dass Ihre Variablennamen einen Teil der Entscheidungen enthalten, aber Sie können sie nicht vermeiden.

Der richtige Code sagt Ihnen " wie ". Die richtigen Kommentare verraten Ihnen das " Warum " .

Aus diesem Grund dokumentiert Code möglicherweise die Art und Weise, wie Dinge erreicht werden, aber Sie können nicht davon ausgehen, dass er den Grund dafür dokumentiert.

Wenn sie auf einer Schwarz-Weiß-Antwort bestehen, für die kein Mittelweg zulässig ist, lautet die Antwort Nein.

Die vollständigere Antwort ist, dass Code sich in einem angemessenen Umfang selbst dokumentieren sollte, aber es gibt keine vernünftige Möglichkeit, einige Arten von Dokumentation in den Code aufzunehmen. Nur zum Beispiel kann der Code eine Geldstrafe darstellen, um zu dokumentieren, welche Informationen auf Formular A, welche auf Formular B und welche auf Formular C gesammelt wurden. Er wird im Allgemeinen nicht versuchen (und sollte es wahrscheinlich auch nicht tun), Tests zu dokumentieren, die diese Aufteilung zeigen Die so erhöhten Daten haben die Fehler um x% reduziert, verglichen mit (zum Beispiel) nur zwei statt drei Formularen.

Alles andere als der trivialste Code kann von zumindest einer externen Dokumentation profitieren.

Meine Antwort. Sie sollten sich so weit wie möglich bemühen, Ihren Code so selbstdokumentierend wie möglich zu gestalten. Dafür gibt es viele Gründe. Beim ersten Schreiben hat durchschnittlich jede zehnte Zeile einen Fehler. Fehler im Code werden häufig gefunden und behoben. Fehler in der Dokumentation bleiben in der Regel zurück. Und bei der Wartung kommt es häufig vor, dass Code und Dokumentation auseinander driften.

Das heißt, es gibt Einschränkungen, was getan werden kann, indem Code klargestellt wird. In diesen Fällen müssen Sie dokumentieren.

Was ist mit dem Fall, in dem Sie die Wahl haben, zu dokumentieren? Meiner Ansicht nach hängt die Wartung stark von Ihrer Organisation ab. Wenn Sie exzellente Softwareentwickler und einen strengen Codeüberprüfungsprozess haben (wie zum Beispiel Google), können Ihr Prozess und Ihre Mitarbeiter so sein, dass Sie sich nicht um Kommentare sorgen müssen, die nicht gepflegt werden. In diesem Fall macht ein viel kommentarreicherer Stil sehr viel Sinn. (Google hat in der Tat einen kommentarreichen Stil.) Wenn Sie jedoch eine typischere Organisation haben, werde ich allen Kommentaren, die ich sehe, zutiefst misstrauen und hoffe, dass Sie Menschen hatten, die daran geglaubt haben beim Versuch, Code selbstdokumentierend zu machen. In dieser Situation halte ich Kommentare für überflüssig.

Eine interessante Unterhaltung über die Vor- und Nachteile des Kommentierens finden Sie unter http://www.perlmonks.org/index.pl?node_id=65153. Dort finden Sie eine alte Unterhaltung, an der ich beteiligt war. (Zur gleichen Zeit, als wir dieses Gespräch führten, gab es eine Reihe privater Chats, die freundlicher waren. Ich habe es immer bedauert, dass nur die negativere Hälfte des Gesprächs öffentlich ist.) Meine Meinungen stimmen nicht mehr genau mit denen überein, die ich damals dachte , aber ich denke immer noch, dass das Gespräch zum Nachdenken anregt.

Ich finde, dass diese Frage sehr häufig auftaucht und oft eine religiöse Begeisterung hat. Hier ist meine Meinung dazu ...

In einer idealen Welt könnte die folgende Aussage getroffen werden:

Code sollte so geschrieben sein, dass die Logik ohne Kommentar befolgt werden kann.

OK, das ist fair genug, aber das Problem ist, dass wir nicht in einer idealen Welt leben. Es gibt einige Probleme beim Erreichen dieser idealen Aussage.

1. Programmierer sind oft nicht die Experten in der Branche, gegen die sie programmieren. Es ist einfach genug, eine Funktion zu verstehen, so wie startEngine(Car car)(die meisten) verstehen können, was hier gefragt wird. Aber bewege dich in die reale Welt, und die Dinge werden etwas unübersichtlicher. Zum Beispiel wäre die Funktion getSess(String tid, String aid)für einen Transportingenieur, der DWDM-Systeme versteht, vollkommen verständlich, kann jedoch für den neuen Programmierer, der gerade das Projekt erstellt hat, eine Herausforderung darstellen. Gut platzierte Kommentare können den Übergang zum rechtzeitigen Verstehen des Codes erleichtern.

2. Programmierer, die zur Pflege des Codes aufgefordert werden, sind häufig nicht so erfahren wie die Originalarchitekten des Codes. Der ursprüngliche Programmierer kann geschickt genug sein, um einen schnellen, prägnanten und effizienten Algorithmus zu schreiben, um eine bestimmte Aufgabe zu erfüllen. Aber der Programmierer, der beauftragt ist, diesen Code zu pflegen, kann Schwierigkeiten haben, zu verstehen, was vor sich geht. Gut platzierte Kommentare können den Übergang zum rechtzeitigen Verstehen des Codes erleichtern.

3. Wie oft haben Sie ein Stück Code geschrieben, das Sie später nur schwer nachvollziehen konnten, warum Sie das getan haben oder was Sie eigentlich erreichen wollten? Das machen wir alle von Zeit zu Zeit. Ein Problem zu lösen und eine leicht verständliche Lösung für ein Problem zu finden, sind oft zwei verschiedene Denkweisen. Wenn Sie nicht die Person sind, die Code perfekt aus dem Gatter heraus schreiben kann, machen Sie oft viele Fehltritte mit Ihrem Code, während Sie fortfahren. Möglicherweise können Sie auch für eine Weile nicht auf dieses Codebit zurückgreifen. Gut platzierte Kommentare können den Übergang zum rechtzeitigen Verstehen des Codes erleichtern.

4. Einzigartige Situationen bedürfen einer Erklärung. Ein Programmierer könnte sich beispielsweise fragen, warum eine 100-ms-Pause in einen Code eingefügt wurde, der mit einem DWDM-Gerät kommuniziert. Dem nächsten Programmierer mitzuteilen, dass eine Pause erforderlich ist, weil das Gerät langsam aufnimmt und der Befehl möglicherweise nicht ausgeführt wird, wäre eine wertvolle Information. Gut platzierte Kommentare können den Übergang zum rechtzeitigen Verstehen des Codes erleichtern.

Schön geschriebener, "selbstdokumentierender" Code ist eine Freude zu finden. Schön geschriebener, "selbstdokumentierender" Code mit gut platzierten, informativen Kommentaren ist ein Glücksfall und ein sehr seltener Fund.

Nur um auf jeder Seite der Ausgangsfrage Argumente vorzutragen:

Ja, Code ist selbstdokumentierend. Die Variablen, Methoden und Klassennamen können so gestaltet werden, dass sie leicht zu lesen und zu verstehen sind, sodass dies eine Form der Selbstdokumentation ist. Möglicherweise enthält der Codestil am Ende eine XML-Dokumentation, die als Standardprozedur betrachtet wird. Mit anderen Worten, es gehört zur Aufgabe des Entwicklers, Dokumentation bereitzustellen, die mit dem Code gemischt werden kann.

Nein, Code ist nicht selbstdokumentierend. Die getroffenen Geschäftsentscheidungen, Designentscheidungen und andere Faktoren werden in den Codezeilen nicht angezeigt und sollten außerhalb der Codebasis notiert werden. Daher ist eine externe Dokumentation erforderlich, und dies sind Beispiele dafür.

Fragen: Würden Sie eine Teilantwort geben, die die Grenzen einer Antwort anerkennt, oder würden Sie sich blindlings auf die Seite stützen, die Sie für die bessere Praxis halten? Wie viel Überzeugung haben Sie in Ihrer Antwort, wenn es ein Ja oder Nein ist? Es könnte als stressige Frage angesehen werden, die darauf abzielt, jemanden zum Aufstehen zu bringen, der antworten könnte: "Was zum ...? Das ist die dümmste Frage, die Sie mir jemals stellen könnten. Ich lehne es ab, sie zu beantworten, weil sie beleidigt meine unglaubliche Intelligenz! " als eine ziemlich arrogante und pompöse antwort, die ich mir vorstellen könnte, wie manche menschen mit diesem ton antworten.

Offensichtlich war er ein gelehrter Programmierer im Stil von Knuth. Für einen LP-Schüler muss der Code selbstdokumentierend sein, um gültig zu sein. Die einzig mögliche Antwort ist also "Ja".

Das Problem dabei ist, dass es nicht viele erfahrene Programmiersprachen gibt und keine, die ich in weit verbreiteten kommerziellen Anwendungen kenne. Es müsste also irgendwo eine Nischenposition sein.

Ich vermute, der Interviewer hat nach Folgendem gesucht: "Wie schreibt man selbstdokumentierenden Code?" mit einem impliziten "Wie stehen Sie zur Dokumentation?"

Ich habe einmal einen wirklich inspirierenden Vortrag von einem Typen namens Robert C Martin besucht, in dem er über das Kapitel 'Schreibmethoden' in seinem Buch Clean Code sprach.

Offensichtlich hat er ein bisschen die Position eines Puristen vertreten, aber ich habe seinen Rat befolgt, wenn Sie Ihren Code in kleine wiederverwendbare Methoden zerlegen und einfache Tricks anwenden wie:

• Halten Sie alle Anweisungen innerhalb einer Methode auf derselben Abstraktionsebene
• Inhalt von Kontrollflussbedingung oder Schleifenblöcken in Methodenaufrufen extrahieren
• Wenn Sie feststellen, dass Sie dieselben Parameter an mehrere Methoden in einer Klasse übergeben und eine neue Klasse herauslösen
• Und einfache Tricks wie das Ersetzen kryptischer boolescher Ausdrücke durch Methodenaufrufe
• etc...

Am Ende erhalten Sie lesbaren, etwas selbstdokumentierenden Code (sofern Sie sich um prägnante und dennoch beschreibende Namen bemühen), der einfacher zu verstehen und zu pflegen ist.

Ich fand das Zeug wirklich hilfreich, aber es erfordert Kenntnisse über Entwurfsmuster, um es gut zu machen, und Sie müssen den Ansatz definitiv mit einer Dokumentation über Klassen und Methoden auf hoher Ebene ergänzen.

Normalerweise bezieht sich selbstdokumentierender Code auf die Praxis der Verwendung einer Namenskonvention für Variablen, Funktionen usw., so dass der Zweck des Codes offensichtlich ist. Kein Code selbst ist also nicht selbstdokumentierend. Ich verstehe nicht, worauf Sie sich im dritten Absatz beziehen. Das scheint nichts mit selbstdokumentierendem Code zu tun zu haben.

Jack Reeves machte ein überzeugendes Argument, dass Code Design ist . Für viele ist der eigentliche Code das einzige "Dokument", das Ihnen sagt, was das System tut. Alles andere verfällt, da ein lebendes System dazu neigt, sich immer weiter von dem entworfenen System zu entfernen. Selbst wenn Sie ein Dokument aus dem Code generieren (wie es viele UML-Tools heutzutage tun können), ist dies nur eine genaue Dokumentation des Systems zu diesem Zeitpunkt .

Also ja, Code ist selbstdokumentierend. Wie gut es dokumentiert ist, ist insgesamt eine andere Frage.

Als ich erfahrener geworden bin, habe ich gelernt, dass die eigentliche Antwort darin besteht, dass der Code und die Umgebung des Lesers den Grad der Selbstdokumentation bestimmen.

Um die Varianz zwischen der Umgebung des Lesers und der Umgebung des Schreibers zu minimieren, fügen wir Kommentare hinzu. Je mehr Kommentare benötigt werden, desto weniger Erfahrung hat der Autor. Es gibt einen wunderbaren Aufsatz, der diesen Aspekt der Softwareentwicklung beschreibt, aber ich kann mich nicht erinnern, wer ihn geschrieben hat oder wo ich ihn gefunden habe.

Ich weiß, die Antwort, die die meisten Leute auf diese Frage erwarten, wäre "nein", aber ich werde ja sagen. Wenn ich dies in einem Vorstellungsgespräch für einen Job gefragt würde, würde ich immer noch Ja sagen.

Ich habe an vielen verschiedenen Projekten mit Open und Closed Source gearbeitet. Sie reichten in der Dokumentation von einfachen Kommentaren, die als Anmerkungen des Programmierers hinterlassen wurden, bis zu vollständigen API-Dokumentationen. Obwohl die API-Dokumentation großartig sein kann, habe ich immer eine Situation erreicht, in der die Dokumentation in schriftlicher Sprache nicht ausreichte, um das tatsächliche Verhalten des Codes zu bestimmen. Am Ende habe ich mir den Quellcode angesehen, die Anwendungen zurückentwickelt oder Entwickler mit dem Quellzugriff belästigt, um den Quellcode zu betrachten und weitere Details anzugeben.

Für mich ist der Code die ultimative Dokumentation. Egal wie viel Sie in Worten schreiben, was ein Programm tun wird, das genaue Verhalten wird durch den Code definiert.

Ich bin damit einverstanden, dass Sie beim Schreiben von Code versuchen sollten, Ihren Code so selbstbeschreibend wie möglich zu gestalten. Wie andere bereits erwähnt haben, ist es in einem komplexen Programm fast unmöglich, alles, was der Code tut, vollständig zu beschreiben. Ich bin nicht gegen Kommentare, in der Tat finde ich, dass es mit guten Kommentaren einfacher sein kann, Code zu lesen, obwohl der Code sich selbst erklären könnte, ohne dass die Kommentare Englisch oder eine gesprochene Sprache lesen, ist fast immer einfacher.

Ich habe festgestellt, dass die nützlichste Dokumentation fast nie Kommentare sind. Die meisten Projekte, an denen ich in letzter Zeit gearbeitet habe, enthalten Wikis, die die verschiedenen Teile und deren Verbindung enthalten. Ich versuche zu erklären, woran ich dachte, als ich den Code schrieb, damit andere meinen Code nicht kaputtmachen, weil sie das Warum nicht verstanden haben. Es kann auch jemand anderem helfen, den Code sicherer umzugestalten. Ich finde mich oft zögernd, Code umzugestalten, weil ich nie weiß, was es brechen könnte und es keine Erklärung gibt. Selbst wenn Sie die einzige Person sind, die an einem Projekt arbeitet, die ich in ein oder zwei Jahren garantiere, werden Sie vergessen, warum Sie etwas getan haben, auch wenn es das schönste Stück Code ist, können Sie immer noch vergessen, warum es dort ist.

Sicher, wenn Sie unbegrenzte Zeit haben. Ich habe mehr als 25 Jahre damit verbracht, Code für andere Entwickler zu dokumentieren. Mein Standpunkt war immer, dass ich versuche, etwas zu erklären, damit ein anderer Entwickler es in 5 Minuten untersuchen und es in einer halben Stunde herausfinden kann. Wenn ich jedem, der sich diese Methode ansieht, 25 Minuten speichere, dann habe ich meine Arbeit erledigt.

Ich denke, dass das Klassendiagramm immer verwendet werden sollte, um den Code zu dokumentieren. Ich glaube nicht, dass Sie die gesamte Architektur sehen können, wenn Sie sich den Code direkt ansehen. Ich bin damit einverstanden, dass Sie verstehen können, wenn Sie den Code selbst geschrieben haben oder lange daran gearbeitet haben, aber jedes Mal, wenn eine neue Nachfrage entsteht, müssen Sie den Code überprüfen und suchen, wo Sie diesen neuen Code hinzufügen können.

Was wir in unserem Unternehmen tun, ist, Klassendiagrammansichten unseres Projekts zu haben. Wir verbringen keine Zeit mit der Modellierung, sondern verwenden nur Klassendiagramme, um den Code nach einem Reverse Engineering zu visualisieren. Wenn sich der Code ändert, gibt es einen Zusammenführungsmechanismus und meine Klassendiagramme werden immer aktualisiert.

Was fantastisch ist, ist in der Lage zu sein, Kommentare und Einschränkungen zusätzlich zu Java Doc in das Diagramm einzufügen. Wir kehren das Projekt um, erstellen dann ein Modell und extrahieren abschließend Ansichten aus dem Modell, die als UML-Klassendiagramme angezeigt werden. Ich programmiere derzeit noch nicht, erhalte aber einen Entwurf für die Codearchitektur und arbeite daran, um meine aktuelle Architektur zu erstellen oder zu erweitern. Wenn es mir gefällt, drücke ich einen Knopf und mein bestehender Code wird mit meinen Diagrammen zusammengeführt. Ich meine Zusammenführen und schon gar nicht vollständige Codegenerierung. Es wird nur das Delta zwischen vorhandenem Code und meinen Diagrammen geschrieben, nicht jedes Mal der vollständige Code.

Ich studiere seit vielen Jahren, habe einen Master-Abschluss und noch Code, aber ich möchte nicht nur ein Java-Schriftsteller sein und möchte mein Gehirn ein wenig mehr nutzen. UML-Ansichten geben mir das, was ich brauche, um über meine Architektur nachzudenken, mit den anderen Teammitgliedern zu kommunizieren und eine bessere Architektur zu erstellen, ohne die modellgetriebene Entwicklung zu verwenden, sondern nur das Delta zwischen vorhandenem manuell geschriebenem Code und grafisch erstellten Klassendiagrammen. Ich erstelle meine Architektur auf Codeebene, kehre sie dann um und schaue mir das Modell an. Ich erstelle Ansichten und versuche, meine Architektur direkt im Code zu verbessern, dann wieder umzukehren und zu sehen, was getan wird usw. Es handelt sich um eine permanente Iteration ohne modellgetriebene Codegenerierung, sondern um Live-Synchronisation oder Zusammenführung von Code und UML. Was mir gefällt ist, dass der Code die UML antreibt und nicht das Gegenteil.