Ist das Lesen von Javadoc dem Lesen von Quellcode vorzuziehen, um sich mit einer Bibliothek vertraut zu machen?

Ich bin gerade in einem Laborhandbuch an der Universität auf Folgendes gestoßen:

Sie müssen die Schnittstellen der Klassen studieren, indem Sie das Javadoc für sie generieren, damit Sie wissen, welche Operationen bereitgestellt werden (Sie können sich den Code ansehen, aber wenn Sie wie hier den Code eines anderen verwenden, sollten Sie nicht über das Javadoc arbeiten den Code wann immer möglich).

Ich verstehe nicht, warum das so ist; da der Javadoc veraltet sein könnte oder die Funktion des Codes schlecht beschreiben könnte. Sicherlich ist es am besten, sich den Quellcode anzuschauen und die Javadoc-Kommentare zu lesen?

Gibt es einen Grund, warum oder einen Fall, in dem nur das Javadoc gelesen wird, das Beste ist?

source-code comments javadocs

— Todd Davies
quelle

In den meisten Fällen haben Sie keine Chance, den gesamten Code zu lesen und zu verstehen, den Sie benötigen würden. Aus dem Code kann auch nicht ersichtlich sein, wie Randfälle behandelt werden.

— Raptortech97

dies wurde viele Male gestellt und beantwortete vor, beginnend mit erster Frage an dieser Stelle - „Kommentare sind ein Codegeruch“ und mehr Fragen verknüpft , um es

— gnat

Antworten:

Bei der Empfehlung geht es wahrscheinlich eher um die Programmierung auf eine Schnittstelle als um die Implementierung .

Sicher, wenn Sie Zugriff auf den Code haben, hindert Sie nichts daran, die Implementierung zu betrachten, um zu verstehen, wie sie funktioniert. Sie sollten jedoch immer sicherstellen, dass das Wie Ihren API-Verbrauch nicht beeinflusst.

Wenn Sie eine API verwenden, arbeiten Sie gegen eine Abstraktion. Versuchen Sie, sich nur mit dem zu befassen, was die API bietet (der Vertrag) und nicht mit dem Wie (der Implementierung).

Dies liegt daran, dass nicht garantiert werden kann, dass sich die Implementierung einer API nicht drastisch von einer Version zur nächsten ändert, selbst wenn der Vertrag unverändert geblieben ist.

— MetaFight
quelle

Eine der größten Auslassungen in vielen Klassendokumentationen ist eine klare Angabe, auf welche Aspekte des offensichtlichen Verhaltens einer Klasse sich die Verbraucher legitim verlassen können (und sich in zukünftigen Versionen der Klasse nicht ändern dürfen) und welche Verhaltensweisen legitim sein dürfen geändert und kann daher nicht legitim verlassen werden. Zum Beispiel, während es für eine Abbildung Sammlung haben teuer wurde jede garantierte Reihenfolge der Aufzählung zu liefern , nachdem alle Elemente gelöscht, es ist billig zu garantieren , dass solange keine Produkte haben jemals gelöscht wurden, werden die Punkte in der Reihenfolge aufzählen wurden fügten sie hinzu.

— Supercat

In vielen Fällen muss Code möglicherweise eine Zuordnungssammlung aus einer Folge von Elementen erstellen und später Elemente in der ursprünglichen Reihenfolge verarbeiten. Wenn die Sammlung garantiert, dass die Elemente in der Reihenfolge aufgelistet werden, in der sie hinzugefügt wurden, kann die ursprüngliche Reihenfolge sicher aufgegeben werden, aber ohne eine solche Garantie muss sie beibehalten werden. Das Dokumentieren eines Verhaltens, an das sich die Klasse "natürlich" halten würde, würde die Implementierung nichts kosten, hätte die Klasse jedoch nützlicher gemacht.

— Supercat

@supercat: Das schränkt jedoch das spätere Optimieren / Umschreiben der Klasse ein. Was bedeutet, dass eine unglückliche Entscheidung niemals korrigiert werden kann.

— Deduplikator

@Deduplicator: Es gibt Kompromisse; Die Frage ist, ob es sich lohnt, auf einen potenziellen Nutzen für die Verbraucher zu verzichten, um bestimmte Arten möglicher Umsetzungsänderungen zu ermöglichen. Ich würde vorschlagen, dass das YAGNI-Prinzip es vorziehen würde, den Verbrauchern die Vorteile zu bieten, es sei denn, man kann tatsächlich die Art von Änderungen artikulieren, die man vornehmen möchte, und man wäre nicht in der Lage, solche Änderungen effizient zu berücksichtigen, ohne den Verbrauchern die Vorteile zu verweigern. Alternativ könnte man eine haben, AddOnlyDictionarydie verspricht, die

— Einfügereihenfolge

... die Sicherheit von Threads mit einem Writer und mehreren Lesern, oder stellen Sie fest, dass andere Arten von Wörterbüchern, wenn sie benötigt werden, abgeleitet werden Dictionarykönnten und die Benutzer beim Schreiben von Code, der das alte Verhalten nicht benötigte, auf das neue migrieren könnten. Beachten Sie, dass die Möglichkeit, die Additionsreihenfolge beizubehalten, im Allgemeinen nicht für Code relevant ist, der eine von einer anderen Stelle empfängtDictionary (da bei einem von einer anderen Stelle empfangenen Wörterbuch möglicherweise irgendwann ein Element gelöscht wurde), sondern nur für Code, der Instanzen über den Konstruktor erstellt. Auf jeden Fall, wenn ein Wörterbuch eine Garantie für zusätzliche Bestellungen nicht

— einhält

Neben dem bereits in der vorherigen Antwort erläuterten Unterschied zwischen der Schnittstelle und der Implementierung gibt es noch einen weiteren wichtigen Aspekt: die Komplexität .

Reale Systeme sind normalerweise komplex. Wenn Sie anfangen, den Code einer Klasse zu lesen, werden Sie feststellen, dass Sie auch den Code einer anderen Klasse lesen sollten, dann einer anderen usw. Ein paar Stunden später verlieren Sie sich einfach in all der Komplexität und Ich werde mich nicht erinnern, wer was und in welchen Fällen anruft.

Wenn Sie nur die Kommentare der Benutzeroberfläche verwenden, verringern Sie all diese Komplexität. Es könnte sein, dass unter der Haube alles einfach ist. Oder es kann sein, dass unter der Haube Dutzende oder Hunderte von Klassen miteinander interagieren, was es praktisch unmöglich macht, das gesamte Bild im Kopf zu behalten.

Sie können ein Experiment durchführen.

Finden Sie einen Teil in OpenCV, der Sie interessiert. Lesen Sie die Schnittstellendokumentation durch. Wie lange dauert es, um die Grundlagen zu verstehen und die Bibliothek effektiv zu nutzen?
Jetzt sehen Sie die Implementierung . Wie viele Klassen werden direkt von der Schnittstelle aufgerufen? Wie viele Klassen werden von jeder dieser Klassen aufgerufen? Wie viele Codezeilen gibt es? Wie viele Methoden? Wie lange würde es dauern, bis Sie den gesamten Quellcode untersucht haben, bevor ein Stapelüberlauf in Ihrem Gehirn auftritt?

— Arseni Mourzenko
quelle

Das muss der Grund sein, warum Updates so lange dauern und warum Sicherheitslücken so lange bestehen bleiben, ohne entdeckt zu werden, weil es so schwierig ist, die Implementierung eines hoch entwickelten Programms zu überprüfen. Ich habe versucht, nur die Java-Quelle der ersten beiden Semester eines Java-Programmierkurses zu überprüfen. Ich denke, es gab keine Klasse, die nicht mindestens zwei andere Klassen anrief, und diese Klassen, die sie anriefen, nannten auch eine beliebige Anzahl von Klassen. Ich war nie in der Lage, einer Code-Spur bis zur endgültigen Fertigstellung zu folgen. Es würde einfach zu lange dauern und es war zu schwierig zu verfolgen, wo ich mich in und

— Progfram

Gibt es einen Grund, warum oder einen Fall, in dem nur das Javadoc gelesen wird, das Beste ist?

Obwohl Sie völlig richtig sind, dass JavaDoc möglicherweise veraltet oder schlecht ist, hat es in der Regel ein besseres Format zum Lesen im Großhandel als Code in einer IDE. Und was noch wichtiger ist, es ist in natürlicher Sprache. Das ist in zwei Fällen wichtig:

Leute, die nicht daran gewöhnt sind, Code zu lesen. Studenten zum Beispiel werden wahrscheinlich häufiger besser durch das Lesen von Funktionsbeschreibungen in natürlicher Sprache bedient als durch den Versuch, Code zu verstehen, den sie gerade lernen.
Personen, die kein Englisch (oder Sprachen, die mindestens phonetische Alphabete verwenden) als Hauptsprache verwenden. Da JavaDoc mit Zeichen arbeiten kann, die Bezeichner nicht können, kann es bessere Beschreibungen der Vorgänge für diese Benutzer liefern. Insbesondere JavaDoc scheint sogar die Möglichkeit zu haben, die Dokumentation für Sie zu lokalisieren .

Trotzdem glaube ich ziemlich stark an lesbaren Code. Für erfahrene Entwickler erwarte ich, dass das Lesen des Codes fast immer ein besserer Ansatz ist, wenn diese Option verfügbar ist.

— Telastyn
quelle