Eine KI in einem großen Java-Backend an Codestil und Modulregeln halten

## Vor dem Bearbeiten verstehen, wie Module und Anbieter zusammenspielen Ein großer Server dieser Art wird aus Modulen zusammengesetzt und nicht als eine einzige Anwendung geschrieben. Eine Moduldeklaration benennt das Modul und die Dienstschnittstellen, die es bereitstellt; ein Anbieter setzt diese Dienste mit genau einer bestimmten Technologie um; andere Module nutzen ausschließlich die deklarierten Schnittstellen. Anbieter werden über den Dienstlademechanismus der Plattform gefunden und folgen einem festen Lebenszyklus: zuerst eine Vorbereitungsphase, die Objekte aufbaut und die Konfiguration liest, dann eine Startphase, die die Dienste aktiviert. ### Die Verarbeitungskette nachvollziehen, bevor du eine Stufe anfasst Sammler senden Telemetriedaten über die Transportschicht, Empfangserweiterungen zerlegen und prüfen sie, die Analysekomponente fasst sie über die projekteigenen Fachsprachen zusammen, Speichererweiterungen legen das Ergebnis dauerhaft ab, und Abfrageerweiterungen liefern es an die Oberfläche. Eine Änderung in einer Stufe braucht meist ein Gegenstück in einer anderen. ### Zuerst die Einstiegspunkte lesen Lies vor jeder Änderung die Definition des Kernmoduls, die Basisklasse des Modulsystems, die Grammatikdateien der domänenspezifischen Sprachen, den Einstiegspunkt der Anwendung und die Architekturdokumentation. Ein Name sagt dir nicht, wie eine Funktion arbeitet. ## Den Codestil einhalten, der beim Bauen automatisch geprüft wird Der Stil wird hier maschinell geprüft, deshalb blockiert ein Verstoß den Bauvorgang und löst keine Diskussion aus. Gib nichts auf der Standardausgabe aus; verwende die Protokollierungsfassade des Projekts. Füge keine Autorenannotationen hinzu. Verwende keine Tabulatorzeichen, keine Sternchenimporte, keine unbenutzten oder überflüssigen Importe, keine leeren Anweisungen und nicht mehrere aufeinanderfolgende Leerzeilen. Schreibe genau eine Anweisung pro Zeile, setze ein Leerzeichen nach Kommas, Semikolons und Typumwandlungen und lasse um Operatoren herum Leerzeichen stehen. ### Vorgeschriebene Muster Kennzeichne überschriebene Methoden mit einer Annotation. Überschreibe Gleichheit und Hashwert immer gemeinsam. Gib jeder Parameter-, Rückgabe- und Ausnahmemarkierung in der Dokumentation eine echte Beschreibung. Schreibe Konstanten vom Typ long mit einem großgeschriebenen Suffixbuchstaben. Ordne den Standardzweig in einem switch als letzten an. Halte die maximale Dateilänge ein und teile jede Datei auf, die sich ihr nähert. ### Benennung Konstanten und statische Variablen werden in Großbuchstaben mit Unterstrichen geschrieben, Typparameter in Großbuchstaben, Typen in Pascal-Schreibweise und lokale Variablen, Parameter sowie Klassenmitglieder in Kamel-Schreibweise. Bevorzuge Fabrikmethoden für unveränderliche Sammlungen und den Annotationsprozessor des Projekts gegenüber handgeschriebenem Standardcode, und bevorzuge lokale Variablen und Parameter, die als final deklariert sind. ### Vollqualifizierte Klassennamen nicht direkt in den Code schreiben Füge einen Import hinzu und verwende den Kurznamen in Felddeklarationen, Methodensignaturen, lokalen Variablen und generischen Argumenten. Die einzigen zulässigen Ausnahmen sind eine echte Kollision der Kurznamen zweier importierter Klassen sowie ein einzelner Verweis in der Dokumentation, bei dem der Kurzname für Lesende mehrdeutig wäre. ### Keine einzeiligen Weiterleitungsmethoden schreiben Eine Hüllklasse, deren gesamter Rumpf nur an eine andere Klasse weiterleitet, fügt einen Zwischenschritt ohne Nutzen hinzu. Setze den Aufruf an der Verwendungsstelle direkt ein oder rufe das zugrunde liegende Objekt unmittelbar auf, auch per Methodenreferenz. ### Lizenzköpfe Quelltext-, Auszeichnungs- und Konfigurationsdateien tragen den Lizenzkopf des Projekts. Formate, die keine Kommentare aufnehmen können, sind in der Lizenzkonfiguration ausgenommen; richte dich nach dieser Konfiguration, statt Lizenzköpfe von Hand dort einzufügen, wo sie nicht hingehören. ## Klassen und Methoden nach ihrer Aufgabe benennen, nicht nach Metaphern Klassen und Methoden werden nach ihrer Funktion benannt und nicht nach einer abstrakten Metapher. Bevorzuge konkrete Verben wie laden, anwenden, abmelden, übersetzen, prüfen, festschreiben und zurückrollen gegenüber metaphorischen wie aussäen, bewässern, urladen und vorfüllen. ### Der Name soll die Aufgabe benennen Eine Klasse, die statische Regeln lädt, wird nach dem Laden statischer Regeln benannt und nicht nach einem stimmungsvollen Bild. Ein Zeitgeber, der den Datenbankzustand nach Zeitplan abgleicht, wird nach diesem Abgleich benannt und nicht nach einem Ticken. ### Eine Metapher ist ein Signal zum Aufteilen Wenn du eine Methode nicht benennen kannst, ohne zu einer Metapher zu greifen, tut die Methode wahrscheinlich zu viel. Teile sie so lange auf, bis jedes Teilstück einen schlichten, sachlichen Namen hat. ## Nur kommentieren, was der Code nicht selbst erklärt Erkläre nicht, was der Code bereits aussagt. Kommentiere nur dort, wo das Lesen des Codes nicht ausreicht: eine Invariante, die in dieser Methode nicht sichtbar ist, eine übergreifende Reihenfolgebedingung, den Grund für einen nicht offensichtlichen Zweig, den Grund dafür, dass ein scheinbar überflüssiger Aufruf nötig ist. Wenn der Code klar ist, schreibe keinen Kommentar. ### Logik verbinden, die an getrennten Stellen liegt Eine Prüfung, die es nur wegen einer an anderer Stelle gegebenen Zusicherung gibt, verdient einen einzeiligen Hinweis auf diese Zusicherung. Eine Behelfslösung für einen bekannten Fehler an anderer Stelle verdient einen Verweis darauf. ### Wiederholende Dokumentation kürzen Die Dokumentation einer Methode beschreibt den Vertrag, nicht den Rumpf. Eine Begründung über mehrere Absätze gehört in das Entwurfsdokument und nicht in die Quelldatei. ## Zusicherungen des Testrahmenwerks nutzen und vor dem Ändern von Tests nachfragen Verwende immer die Zusicherungsmethoden des Testrahmenwerks. Verwende in einem Test niemals die eingebaute Zusicherungsanweisung der Sprache. Auch dort, wo der Testausführer diese Anweisungen zufällig aktiviert, sind die Zusicherungen des Rahmenwerks die Konvention im übrigen Code, überstehen jede Konfiguration des Testausführers und erzeugen einen strukturierten Fehlschlag, der den tatsächlichen Wert benennt, statt eines Fehlers ohne Zusammenhang. ### Fehlschlagende Tests reparieren, nicht stillschweigend verändern Wenn bestehende Komponenten-, Integrations- oder Ende-zu-Ende-Tests fehlschlagen, versuche sie zu reparieren. Wenn ein Testfall geändert oder Testcode gelöscht werden muss, muss diese Änderung von einem Menschen gegengeprüft werden, bevor sie angewendet wird: Lege die vorgeschlagene Änderung oder Löschung samt Begründung offen und warte auf eine ausdrückliche Freigabe, statt den Test selbst zu ändern oder zu entfernen. ### Die Testart auf den Geltungsbereich abstimmen Die Ebenen Komponententest und Integrationstest verwenden unterschiedliche Muster und unterschiedliche Testgerüste. Weise Verhalten auf der Ebene nach, auf der es tatsächlich angesiedelt ist, statt dieselbe Zusicherung auf jeder Ebene zu wiederholen. ## Code schreiben, der auf der ältesten unterstützten Java-Version kompiliert Ein Projekt, das mehrere Ausgaben mit Langzeitunterstützung trägt, muss sich auf der ältesten übersetzen lassen und dort laufen, auch wenn auf dem Baurechner ein neuerer Übersetzer liegt. Geh von der Mindestversion aus und nicht davon, was dein Editor akzeptiert. ### Konstrukte, die bei einer älteren Mindestversion zu vermeiden sind switch-Ausdrücke in Pfeilform, der Datenstromabschluss, der direkt eine Liste zurückgibt, Textblöcke, Datensatztypen, Musterabgleich in einer Typprüfung und versiegelte Typen sind allesamt neuer als eine ältere Basisversion. Verwende stattdessen ein herkömmliches switch mit ausdrücklichen case- und break-Anweisungen, einen Sammler zum Aufbau der Liste, Zeichenkettenverkettung, eine gewöhnliche Klasse mit erzeugten Zugriffsmethoden, eine ausdrückliche Typumwandlung nach der Typprüfung sowie eine gewöhnliche Klasse oder Schnittstelle. ### Konstrukte, die unbedenklich sind Fabrikmethoden für unveränderliche Sammlungen, die neueren Methoden auf Optional, Lambda-Ausdrücke, Methodenreferenzen und die Datenstromschnittstelle selbst stehen auf einer älteren Basisversion zur Verfügung und brauchen keine Behelfslösung. ### Durch Suchen prüfen, nicht dem Bauvorgang vertrauen Durchsuche den Quellcodebaum nach jedem verbotenen Konstrukt und stelle sicher, dass es keine Treffer gibt, bevor du Kompatibilität behauptest. Ein Bauvorgang mit einem neueren Übersetzer findet diese Stellen nicht für dich. ## Untermodule und erzeugten Code mit dem Build synchron halten Protokolldefinitionen und die Weboberfläche können in Untermodulen liegen. Klone das Projekt immer einschließlich der Untermodule und aktualisiere sie ausdrücklich, wenn eine Protokolländerung das erfordert. Eine Protokolländerung, die sich nicht im Verweis auf das Untermodul niederschlägt, lässt sich bei niemandem sonst bauen. ### Erzeugen, bevor du analysierst Führe den Übersetzungsschritt aus, bevor du erzeugten Code analysierst, und installiere das Projekt, damit der Vorübersetzer und die erzeugten Klassen exportiert sind, bevor du Tests ausführst. Bearbeite erzeugte Klassen niemals von Hand; ändere die Definition, aus der sie entstehen, und baue neu. ### Nach modulübergreifenden Änderungen das gesamte Projekt neu bauen Wenn du mehr als zwei Module geändert oder Änderungen vom entfernten Stand geholt beziehungsweise darauf neu aufgesetzt hast, baue das gesamte Projekt, statt einzelne Module auszuwählen. Schrittweise Bauvorgänge für ein einzelnes Modul können veraltete Archive in der lokalen Ablage oder im Bibliotheksverzeichnis zurücklassen, wenn sich die Archivgröße nicht ändert, der Inhalt aber schon; daraus entstehen Laufzeitfehler, die sich nur sehr schwer zurückverfolgen lassen. ## Dokumentation und Änderungsprotokoll richtig halten und korrekt darstellen Die Dokumentation wird von einem Markdown-Aufbereiter dargestellt; achte deshalb darauf, wie sie aussehen wird, und nicht nur darauf, wie sich der Quelltext liest. Relative Dateipfade sind gültig und funktionieren sowohl in der Projektablage als auch auf der Dokumentationsseite; verwende weiterhin sie statt absoluter Verweise. Aktualisiere das Änderungsprotokoll immer dann, wenn sich das Verhalten ändert. ### Jeden Punkt im Änderungsprotokoll auf einer Zeile halten Brich einen Satz innerhalb eines Punktes nicht fest über mehrere Quellzeilen um; verschachtelte Unterpunkte sind in Ordnung, weil sie echte Listeneinträge sind. Aus dem Änderungsprotokoll wird der Beschreibungstext der Veröffentlichung, und der Aufbereiter der Veröffentlichung wandelt schon einen einzelnen fortsetzenden Zeilenumbruch in einen Umbruch um; umgebrochene Punkte zeigen deshalb auf der Veröffentlichungsseite zerrissene Umbrüche mitten im Satz, obwohl die Dokumentationsseite den Text neu umbricht und das Problem verdeckt. ### Einen Entwurfsvorschlag einfrieren, sobald er ausgeliefert ist Wenn die Umsetzung eines Entwurfsvorschlags eingeht, gleiche den Vorschlag einmalig an das an, was tatsächlich gebaut wurde: jede vorgeschlagene Änderung in der Vergangenheitsform, ohne verbleibende Formulierungen zu ausstehenden Arbeiten, künftigen Arbeiten, offenen Abhängigkeiten oder vorläufig leeren Abschnitten für irgendetwas in seinem Geltungsbereich. Nach diesem Abgleich ist der Vorschlag eingefroren. Weitere Kennzahlen, Übersichtsanzeigen und schrittweise Verbesserungen gehören stattdessen in die fortlaufend gepflegte Betriebsdokumentation. Nur wirklich kleine, optionale Nacharbeiten dürfen unter künftigen Arbeiten stehen bleiben; niemals eine große Änderung. ### Querverweise mit Ankerverweisen setzen Verweise auf einen anderen Abschnitt mit einem Ankerverweis in Markdown, niemals mit einem Paragrafenzeichen oder einer bloßen Abschnittsnummer. Prüfe, dass jeder Anker nach den Regeln der Seite zur Bildung von Ankernamen auf eine tatsächlich vorhandene Überschrift führt, denn ein defekter Anker wird stillschweigend als einfacher Text dargestellt. ## Jedes Modul deklarieren, das der Code nachschlägt Jede Suche nach dem Dienst eines anderen Moduls muss durch eine Deklaration abgedeckt sein. Wenn Code den Modulverwalter bittet, ein Modul zu finden, sei es direkt oder über eine Hilfsmethode, muss der Name dieses Moduls in der Liste der benötigten Module des Anbieters stehen. Eine fehlende Deklaration führt nicht beim Hochfahren zu einem Fehler; sie wirft erst dann eine Ausnahme, wenn dieser Codepfad zum ersten Mal ausgeführt wird. Den Aufruf in einen weit gefassten Ausnahmefang zu verpacken, ist kein Ersatz: Deklariere das Modul und behalte die defensive Behandlung nur für vorübergehende Ausfälle eines Anbieters. Wenn du einen Zweig prüfst, durchsuche jedes berührte Modul nach Suchaufrufen an den Modulverwalter und stelle sicher, dass jedes Ziel deklariert ist. ### Jede Implementierung aktualisieren, nicht nur die wichtigste Wenn du der Dienstliste eines Kernmoduls einen Dienst hinzufügst, aktualisiere alle Anbieterimplementierungen dieses Moduls, einschließlich der Attrappenanbieter, die von eigenständigen Werkzeugen und Testgerüsten verwendet werden. Durchsuche den Baum nach Unterklassen, statt anzunehmen, dass es nur eine gibt. Der Hauptserver ist nicht die einzige Auslieferungsform; eigenständige Werkzeuge starten mit Attrappenanbietern und einer Teilmenge der Module, deshalb müssen Änderungen an den Verträgen der Kernmodule auch dort ankommen, sonst schlägt der Start dieser Werkzeuge fehl. ### Den bereits befüllten Dienst dem Koordinierungsmodul vorziehen Empfangs- und Auswertungsmodule deklarieren das Modul für die Koordinierung des Rechnerverbunds meist nicht, deshalb wirft ein direkter Suchaufruf darauf zur Laufzeit eine Ausnahme. Gehe über den Dienst zur Verwaltung der Gegenstellen im Kernmodul, der von der Koordinierungsschicht bereits befüllt wird und der die Liste der Gegenstellen bereitstellt, die von den meisten Komponenten benötigt wird. Wenn ein Modul tatsächlich Koordinierungsprimitive braucht, deklariere dieses Modul ausdrücklich. ### Absichten nicht über threadlokale Seitenkanäle leiten Die Absicht eines Aufrufers über eine threadlokale Variable weiterzugeben, die von nachgelagertem Code ausgelesen wird, erzeugt eine unsichtbare Kopplung zwischen weit entfernten Codepfaden, läuft über asynchrone Übergaben wie Ausführungsdienste und Ereignisschleifen hinweg aus und macht es unmöglich, das Verhalten anhand einer Methodensignatur zu verstehen. Erweitere stattdessen die Schnittstelle: Füge einen Parameter, eine Methode oder einen Moduswert hinzu, der in der Signatur auftaucht, auch wenn das mehr Zeilen kostet. Die seltenen Ausnahmen sind die Weitergabe von Kontext, für die sich die gesamte Branche auf eine threadlokale Variable geeinigt hat, und Sicherheitsidentitäten, die von einem Rahmenwerk durchgesetzt werden. ## Warten, bis die Schemaänderung alle Knoten erreicht hat, bevor Daten geschrieben werden Wenn Änderungen am Schema oder an den Metadaten an Koordinatorknoten verteilt und asynchron an Datenknoten weitergegeben werden, kehrt ein Definitionsaufruf zurück, sobald der Koordinator ihn annimmt, und liefert dabei eine Revisionsmarke, ohne auf die übrigen Knoten zu warten. Ein Schreibvorgang auf Daten, deren Definition sich noch nicht ausgebreitet hat, wird auf dem ausführenden Knoten verworfen, protokolliert und übersprungen; deshalb ist eine Barriere erforderlich. ### Auf den Revisionsstand warten Blockiere nach einer Definitionsänderung an der Schemaüberwachung des Clients, bis jeder aktive Knoten meldet, dass er mindestens die zurückgegebene Revision angewendet hat, begrenzt durch eine Zeitüberschreitung, bevor du abhängige Schreibvorgänge freigibst. Eine Prüfung, die nach dem Schreiben aus der Registrierung liest, beweist die Ausbreitung nicht. ### Löschungen und synchrone Speicher behandeln Wenn eine Löschung keine brauchbare Revisionsmarke zurückgibt, weiche auf den eigens dafür vorgesehenen Aufruf zum Warten auf die Löschung aus. Speicher, deren Definitionsanweisungen auf dem Koordinator synchron ablaufen, brauchen überhaupt keine Barriere. Führe die ältere Gewohnheit nicht wieder ein, den Suchaufruf zyklisch abzufragen, bis du deinen eigenen Schreibvorgang lesen kannst; sie stammt aus der Zeit vor der Barrierenschnittstelle und wurde ersetzt. ### Prüfen, welche Clientbibliothek du gerade liest Barrieren- und Überwachungstypen können in einer im Projektbaum mitgeführten Abspaltung des Clients liegen statt im eigenständig veröffentlichten Client. Dass sie im veröffentlichten Client fehlen, ist kein Beweis dafür, dass es die Schnittstelle nicht mehr gibt. ## Im Quellcode und in der Dokumentation nachsehen, statt zu raten Rate und spekuliere niemals. Jede Analyse muss sich auf Quellcode, Dokumentation oder beobachtetes Verhalten stützen. Lies die Implementierung, statt aus ihrem Namen oder aus Gewohnheit anzunehmen, wie eine Funktion arbeitet. Lies die Projektdokumentation, die Anleitungsdateien in den Untermodulen und die Readme-Dateien, bevor du einen Entwurf vorschlägst. ### Konfiguration und Schalter prüfen Prüfe, welche Schalter und Umgebungsvariablen tatsächlich existieren, welche Vorgabewerte sie haben und wie sie ausgewertet werden, einschließlich jeder Präfixkonvention, die Schalter automatisch an Umgebungsvariablen bindet. ### Die Projekte lesen, von denen du abhängst Bevor du eine Fähigkeit voraussetzt, lies Quellcode und Dokumentation der beteiligten Abhängigkeiten und Begleitprojekte: Auslieferungsvorlagen für unterstützte Felder, Testinfrastruktur für unterstützte Optionen, Clientbibliotheken für verfügbare Aufrufe. Wenn ein Begleitprojekt wahrscheinlich lokal als Arbeitskopie vorliegt, frage nach dem lokalen Pfad, denn das Durchsuchen einer lokalen Kopie ist weit schneller, als Dateien einzeln über eine entfernte Schnittstelle abzurufen. ## Code und Tests lokal ausführen, bevor du dich auf die fortlaufende Integration (CI) verlässt Führe den Code aus, starte den Container und lass den Test lokal laufen, bevor du überträgst. Die fortlaufende Integration ist keine Umgebung zum Ausprobieren auf gut Glück. ### Pfade und Verzeichnisstrukturen überprüfen Prüfe, wo die Daten tatsächlich landen, statt einen Verzeichnisnamen aus einem Schalternamen abzuleiten; eine Option für den Wurzelpfad legt darunter häufig ein anders benanntes Unterverzeichnis an. ### Erzeugte oder bearbeitete Konfiguration überprüfen Wenn du Konfigurationsdateien bearbeitet hast, besonders mit Datenstromeditoren oder Skripten, überprüfe sie mit einem echten Auswerter, bevor du sie festschreibst. Beschädigte Konfiguration führt in der Automatisierung zu stillen Fehlern. ### Bestätigen, dass Abbilder und Programmdateien existieren Vergewissere dich, dass das Containerabbild tatsächlich veröffentlicht ist, bevor du eine Ablaufkette oder eine Ende-zu-Ende-Konfiguration schreibst, die davon abhängt, und stelle fest, welche Programmdateien, Befehlsinterpreter und Verzeichnisse im Abbild vorhanden sind, bevor du Befehle schreibst, die sie verwenden. Die Verfügbarkeit eines Abbilds hängt davon ab, dass die Veröffentlichungsabläufe abgeschlossen sind. Achte darauf, wo die Abbilder liegen: Abbilder des eigenen Projekts können in der Registrierung des Quellcodedienstes liegen und vollständige Kennungen einzelner Codestände als Marken tragen, während offizielle Abbilder und Abbilder von Dritten mit üblichen Marken in der öffentlichen Registrierung liegen. ## Über den Einreichungsablauf des Projekts und freigegebene Automatisierung übertragen Verwende den eigens dafür vorgesehenen Einreichungsablauf des Projekts, um Änderungen festzuschreiben und in einen Prüfzweig zu übertragen. Er führt vor jeder Übertragung Vorabprüfungen wie Übersetzung, Stilprüfung und Kontrolle der Lizenzköpfe aus und eröffnet die Prüfanfrage, falls es noch keine gibt. ### Die Freigabeliste für Automatisierung beachten Die Organisation kann eine Freigabeliste für Automatisierungsschritte von Dritten durchsetzen und verlangen, dass jeder Schritt auf eine freigegebene Revisionskennung festgelegt wird statt auf eine Versionsmarke. Wenn eine Prüfung blockiert wird, weil ein Schritt nicht zugelassen ist, sieh in der Freigabeliste nach und ändere die Ablaufdateien so, dass sie die freigegebene Festlegung verwenden. Schritte, die vom Hersteller der Plattform oder von der Organisation selbst stammen, sind in der Regel ohne Festlegung erlaubt. ### Sagen, was fehlt, statt zu raten Wenn du den Quellcode nicht findest, nicht weißt, wie sich etwas ausführen lässt, oder der Code die Antwort nicht klar erkennen lässt, frage nach, statt zu spekulieren. Wenn du das Laufzeitverhalten untersuchst, richte einen lokalen Test mit echten Daten ein und beobachte die tatsächliche Ausgabe, statt sie vorherzusagen.