Eine Datenbibliothek mit leicht auffindbaren APIs und Tests mit echten Werten bauen

## Komplexe Quelldaten hinter einfachen Objekten verbergen Verbirg die Komplexität des Quellformats hinter intuitiven Fachobjekten, ohne wichtige Fähigkeiten zu verdecken. Gestalte häufige Vorgänge direkt und mache spezielle Funktionen zum Parsen, zur Berichterstellung und zur Prüfung schrittweise zugänglich, sobald die Benutzer sie benötigen. Lies vor dem Schreiben. Prüfe vor einer Codeänderung die bestehenden Abstraktionen, Benennungsmuster, Modulgrenzen und benachbarten Tests. Erweitere den vorhandenen Entwurf, sofern nicht eine konkrete Unvereinbarkeit ein neues Muster erfordert. ## Vor Änderungen festhalten, welches Modul wofür zuständig ist Pflege eine knappe Navigationsübersicht, die Benutzeranforderungen den zuständigen Modulen und wichtigen Fachklassen zuordnet. Nimm die öffentlichen Einstiegspunkte für das Auffinden von Datensätzen, Laden von Entitäten, Parsen strukturierter Daten, Erstellen von Aufstellungen, Lesen von Anmerkungen, Öffnen von Dokumenten und Erzeugen typisierter Berichte auf. Verfolge vor einer Bearbeitung beispielhafte Datenflüsse vollständig. Folge einer Anfrage vom öffentlichen Einstiegspunkt über Abruf, Parsen, typisierte Objekte, Aufstellungen, Anmerkungen und Berichte bis zur Dokumentextraktion. Stelle fest, welche Schicht jede Umwandlung verantwortet und an welcher Stelle Benutzer zu stützenden Einzelheiten vordringen sollen. Nutze die Übersicht, um das kleinste zuständige Modul auszuwählen. Lege Verhalten nicht nur aus Bequemlichkeit in einer Datei ab, wenn bereits eine andere Schicht dafür verantwortlich ist. ## Große Dateien stückweise lesen und eng begrenzt ändern Behandle Module mit mehr als 30 KB als mehrere lokale Zusammenhänge, statt sie als einen Block zu lesen oder umzuschreiben. Suche nach dem betreffenden Symbol, prüfe die umschließende Klasse oder Funktion und lies anschließend ausreichend benachbarten Code, um unveränderliche Bedingungen und Aufrufstellen zu verstehen. Ermittle vor der Änderung einer großen Datei die zugehörigen Tests, Einbindungen, Unterklassen und öffentlichen Verweise. Halte die Änderung eng begrenzt, bewahre die umliegenden Konventionen und vermeide sachfremde Neuformatierungen oder Umstrukturierungen, die die funktionale Änderung verschleiern würden. ## Arbeit in der Vorgangsverwaltung erfassen und aktuell halten Nutze die Vorgangsverwaltung des Projekts als dauerhaften Nachweis laufender Arbeit. Prüfe offene und in Bearbeitung befindliche Einträge, wähle den zutreffenden Vorgang aus und setze ihn vor der Umsetzung auf aktiv. Erfasse neu entdeckte Fehler oder Aufgaben mit eindeutigem Titel, Typ und Vorrang, statt sie nur in Kommentaren oder Unterhaltungen zu hinterlassen. Aktualisiere denselben Vorgang, wenn sich Umfang, Hindernisse oder Schlussfolgerungen ändern. Schließe ihn erst nach Abschluss der erforderlichen Überprüfung. Bewahre die festgelegten Zustände offen, in Bearbeitung, blockiert und geschlossen. Wenn die Vorgangsverwaltung fünf Vorrangstufen verwendet, behalte `0` für kritische Arbeit und `4` für den Arbeitsvorrat bei, statt beliebige Bezeichnungen zu erfinden. ## Prüfen, ob die Bibliothek hält, was ihre Dokumentation verspricht Überprüfung fragt, ob die Bibliothek die Zusagen ihrer Dokumentation erfüllt, nicht nur, ob der interne Code ausgeführt wird. Wende drei maßgebliche Grundsätze an: 1. Die Dokumentation ist die Spezifikation, daher muss jedes dokumentierte Beispiel überprüfbar sein. 2. Die Richtigkeit der Daten ist unverzichtbar, daher müssen Prüfungen konkrete Sollwerte bestätigen und dürfen nicht nur das Vorhandensein eines Ergebnisses feststellen. 3. Die Programmierschnittstelle muss einen Lösungsweg bieten, damit Benutzer und Agenten von einer Frage zum passenden Objekt, Verfahren und stützenden Nachweis gelangen können. Nutze diese Grundsätze, um Funktionsentwurf, Dokumentation, Testfälle und Fehlerverhalten gemeinsam zu bewerten. ## Jeder neuen Funktion einen Test mit echten Werten und ein lauffähiges Doku-Beispiel geben Jede neue benutzerorientierte Funktion muss Folgendes enthalten: - eine Referenzwertprüfung mit einem konkreten Wert aus einem echten Quelldatensatz, der unabhängig geprüft wurde; - ein dokumentiertes Beispiel, das zugleich als automatisierte Überprüfung ausgeführt wird; - eine Prüfung auf stilles Versagen, die belegt, dass ungültige oder fehlende Eingaben einen hilfreichen Fehler statt eines leeren Werts oder eines lautlosen Fehlschlags erzeugen; - eine Aktualisierung zur Auffindbarkeit, durch die die Funktion in der Projektnavigation, im Funktionskatalog oder in den Agentenleitlinien erscheint. Eine Funktion ist unvollständig, sobald eines dieser Elemente fehlt, selbst wenn ihre Umsetzung im regulären Ablauf funktioniert. ## Schnelle lokale Tests zuerst, Netzwerktests nacheinander ausführen Stelle getrennte Befehle für schnelle lokale Überprüfung, netzgestützte Überprüfung, Regressionsüberprüfung und Abdeckungsberichte bereit. Führe zuerst die kleinste zutreffende lokale Prüfung aus und erweitere den Umfang erst, wenn das gezielte Ergebnis bestanden hat. Führe nur schnelle Tests parallel aus, die keine externen Dienste kontaktieren. Führe netzgestützte Überprüfungen nacheinander aus und beachte die Begrenzung der Anfragerate des Dienstes. Nutze aufgezeichnete Antwortprüfdaten, wenn sie externes Verhalten schnell und reproduzierbar machen können, ohne die zu überprüfende Vereinbarung zu verdecken. Lege Regressionsfälle in einem eigenen Bereich mit beständigen Namen ab, die jeden Fall mit dem auslösenden Fehler verknüpfen. Behandle Abdeckung als ergänzenden Nachweis und nicht als Ersatz für Prüfaussagen zu Verhalten und Daten. ## Genaue Werte und klare Fehler mit vielfältigen Quelldaten prüfen Bestätige genaue Fachwerte, normalisierte Strukturen und aussagekräftige Fehlermeldungen. Eine Prüfaussage, die lediglich das Vorhandensein eines Ergebnisses bestätigt, reicht nicht aus, wenn die Richtigkeit vom Wert selbst abhängt. Verteile die Quelldatensätze auf unterschiedliche Organisationen, Branchen, Formate und Berichtszeiträume, statt dich auf ein einziges vertrautes Beispiel zu stützen. Prüfe fehlerhafte, unvollständige und nicht unterstützte Eingaben ausdrücklich. Stelle sicher, dass Fehler handlungsorientierte Meldungen liefern und niemals lautlos zu einem leeren Ergebnis werden. Wenn externe Daten erforderlich sind, bewahre reproduzierbare Prüfdaten auf und dokumentiere, wie ihre Sollwerte ermittelt wurden. Aktualisiere Prüfdaten bewusst, wenn sich die vorgelagerte Vereinbarung ändert; erneuere sie nicht nur, damit eine fehlgeschlagene Prüfung besteht. ## Version und Dokumentation im Einklang mit funktionierendem Code halten Lies die Projektversion aus der dafür vorgesehenen Metadatendatei und vermeide Wiederholungen in nicht zusammengehörigen Modulen. Halte Navigation im Codebestand, Überprüfungsleitlinien, öffentlich zugängliche Beispiele und Funktionskataloge mit dem unterstützten Verhalten im Einklang. Wenn sich ein Pfad der Programmierschnittstelle ändert, aktualisiere Dokumentation und ausführbare Beispiele im selben Arbeitseintrag. Ein dokumentierter Pfad, der nicht mehr funktioniert, verletzt den Vertrag mit den Benutzern, selbst wenn die ersetzende Umsetzung korrekt ist.