reyalka/astro

Kommentare schreiben

Zweck

Kommentare in diesem Repository werden von Mitwirkenden Monate oder Jahre nach ihrer Erstellung gelesen, die keinerlei Kontext haben, den du gerade hast. Diese Skill definiert, wer dieser Leser ist, wofür jede Art von Kommentar gedacht ist und welche Muster verboten sind.

Abgrenzung

Diese Skill gilt für Mitwirkende zugängliche Kommentare im TypeScript/JavaScript-Quellcode. Sie gilt nicht für die Endbenutzer-Dokumentation:

• JSDoc-Blöcke, die mit @docs markiert sind in packages/astro/src/types/public/config.ts und packages/astro/src/core/errors/errors-data.ts werden von einem externen docgen-Tool gelesen und auf der Astro-Dokumentationswebsite veröffentlicht. Befolge packages/astro/src/core/errors/README.md für diese und hole dir eine Überprüfung vom Docs-Team – CI generiert die Referenz neu, wenn types/public/** geändert wird.
• Andere JSDoc-Kommentare in types/public/** werden den Benutzern im Editor-IntelliSense angezeigt. Schreibe sie für Benutzer von Astro, die eine Website erstellen, nicht für Mitwirkende, die den Quellcode lesen.

Alles unten bezieht sich auf den Quellcode, den ein Mitwirkender am aktuellen HEAD liest.

Der Leser

Schreibe für einen Astro-Mitwirkenden, der kompetent in TypeScript ist, aber keinen Zugriff auf deinen aktuellen Kontext hat: nicht auf dieses Gespräch, den Pull Request, das Issue oder den Diff. Sie sehen nur das Repository am HEAD.

Daraus ergeben sich zwei Konsequenzen direkt:

1. Erzähle niemals Änderungshistorie. Wörter wie „jetzt“, „zuvor“, „nicht mehr“, „der neue Ansatz“ sind am HEAD bedeutungslos, wo nur ein Ansatz existiert. Beschreibe, wie der Code funktioniert, nicht wie er zustande kam. (Ein @deprecated-Hinweis ist die Ausnahme – siehe Konventionen – weil er den zukünftigen Vertrag beschreibt, den der Leser benötigt.)
2. Sprich niemals den Reviewer an. Ein Kommentar, der Argumente für die Richtigkeit deiner Änderung liefert („dies behandelt X korrekt“), gehört in die PR-Beschreibung, nicht in den Quellcode. Der Kommentar muss den Code so, wie er ist, dauerhaft rechtfertigen.

Drei Arten von Kommentaren, drei verschiedene Aufgaben

Art	Syntax	Aufgabe	Enthält
Datei-/Modulübersicht	/** */ oben in der Datei	Erklärung	Warum das Modul existiert, Konzepte und Begriffe, die es definiert, Beziehungen der Teile, Design-Entscheidungen
Item-Dokumentation	/** */ direkt über einer Deklaration	Referenz	Der Vertrag: Verhalten, Parameter, Rückgabewert, ausgelöste Fehler, Invarianten. Neutral und sachlich
Inline-Kommentare	// innerhalb eines Rumpfes	Begründung	Nur was der Code nicht sagen kann: Einschränkungen, Workarounds (mit Issue-Links), nicht offensichtliche Kopplungen

Vermische die Aufgaben nicht. Implementierungsdetails gehören nicht in den /** */-Vertrag – setze sie als //-Kommentare in den Rumpf. Der Vertrag gehört nicht auf inline-Kommentare verteilt – setze ihn auf die Deklaration.

Verhalten dokumentieren

Wenn eine Item-Dokumentation gerechtfertigt ist, schreibe den Vertrag für einen menschlichen Leser, nicht als Übersetzung der Implementierung. Dies erfordert nicht für jede Funktion JSDoc; Namen, Typen und Struktur sollten einfaches Verhalten von sich aus tragen.

• Beginne mit einer Beschreibung in einfacher Sprache, was die Funktion zurückgibt oder bewirkt.
• Verwende kurze oder mittellange Sätze mit einem Hauptgedanken pro Satz.
• Vermeide internes Astro-Jargon, wenn Aufrufer ihn nicht benötigen. Wenn ein Fachbegriff nötig ist, erkläre ihn im selben Absatz.
• Beschreibe für Aufrufer sichtbare Einschränkungen, die überraschend sein können: Fallback-Verhalten, Arbeitsgrenzen, mehrdeutige Ergebnisse, Überladungsreihenfolge, Seiteneffekte und Bedingungen, die undefined, null, ein leeres Ergebnis oder einen anderen unbestimmten Wert zurückgeben.
• Dokumentiere ausgelöste Fehler, wenn Aufrufer sie unterscheiden oder davon erholen sollen.
• Beschreibe keine Implementierungsdetails, es sei denn, Aufrufer benötigen sie, um das Verhalten zu verstehen oder die API sicher zu verwenden.

Füge ein Beispiel hinzu, wenn das Verhalten von einer Beziehung abhängt, die die Signatur nicht klar zeigen kann. Häufige Astro- und TypeScript-Fälle sind:

• welche Überladung ausgewählt wird;
• wie Argumente auf optionale oder Restparameter abgebildet werden;
• welcher öffentliche Astro-Einstiegspunkt ein Symbol offenlegt, das anderswo implementiert oder reexportiert wird;
• Fallback-Verhalten für mehrdeutige Routen, unvollständige Konfiguration oder fehlende Inhalte;
• ein Ergebnis, dessen Bedeutung aus seinem Typ nicht offensichtlich ist.

Führe das Beispiel in Prosa vor dem Codeblock ein. Gib an, was es demonstriert und welches Ergebnis erwartet wird. Halte Schnipsel minimal, in sich geschlossen und aus der Perspektive eines Astro-Benutzers oder des internen Aufrufers, der den Vertrag besitzt.

Die Moduldokumentation sollte ein dauerhaftes Konzept, eine architektonische Grenze oder einen Design-Grund beschreiben. Liste keine einzelnen Exporte auf, nur um die Datei zusammenzufassen; solche Inventare werden veraltet, wenn Symbole hinzugefügt oder umbenannt werden. Wenn ein Modul kein dauerhaftes Konzept zu erklären hat, verwende eine kurze einzeilige Beschreibung oder keine Übersicht.

Der Löschtest

Bevor du einen Kommentar schreibst, frage: Sagt dies etwas, das der Leser nicht aus dem Code selbst ableiten kann?

• Wenn die Information bereits durch Namen, Typen oder Struktur getragen wird, schreibe den Kommentar nicht. Wenn der Name sie nicht trägt, verbessere den Namen.
• Informationen, die legitimerweise einen Kommentar benötigen: eine Invariante, eine Begründung, eine Kopplung an Code anderswo, ein Workaround mit einem Link, überraschendes Verhalten einer Abhängigkeit, ein Fachbegriff, den das Modul definiert.

Wenn du später bearbeitest, gilt derselbe Test in umgekehrter Richtung: Ein Kommentar, der ihn nicht mehr besteht, sollte gelöscht werden, nicht verrotten.

Link zum Issue für Workarounds

Dieses Codebase verankert Workarounds konsistent mit einer Quelle. Jeder Kommentar, der einen Workaround, einen HACK, einen Regressionsschutz oder überraschendes Verhalten einer Abhängigkeit erklärt, muss das GitHub-Issue oder den PR verlinken, der ihn motiviert. Der Link ermöglicht es einem zukünftigen Leser festzustellen, ob der Workaround noch benötigt wird.

// Behandle empfohlene nanostores. Nur @nanostores/preact ist laut unseren Tests erforderlich!
// Vollständige Erklärung und zugehöriger Bug-Report: https://github.com/withastro/astro/pull/3667
'@nanostores/preact',

Ein Workaround ohne Link ist von einem Fehler nicht unterscheidbar.

Verbotene Muster

Die nächste Zeile erklären. Lösche diese beim Anblick:

// Erhöhe den Generierungszähler
generation += 1;

Änderungshistorie erzählen. Umschreibe als Begründung im Präsens:

// SCHLECHT: Wir lösen jetzt lightningcss aus dem Benutzerverzeichnis auf, nicht aus unserem.
// GUT: lightningcss ist eine optionale Peer-Abhängigkeit, daher wird es aus dem Projektverzeichnis des Benutzers aufgelöst.

An den Reviewer gerichtete Rechtfertigung. Verschiebe das Argument in die PR:

// SCHLECHT: Dies behandelt korrekt den mehrfach codierten Pfad aus dem Bug-Report.
// GUT: Ein Pfad, der nach MAX_DECODE_ITERATIONS noch codiert ist, wird abgelehnt, sodass
//       Middleware und Routing niemals über den dekodierten Pfad uneins sein können.

Wiederholte JSDoc. Ein /** */-Block, der den Deklarationsnamen umschreibt, sagt nichts:

// SCHLECHT:
/** Kompiliert die Styles. */
function compileStyles(...)

// GUT:
/** Schreibt relative `url()`-Referenzen in `css` gegen `base` um, wobei
 *  absolute und Daten-URLs unberührt bleiben. */
function compileStyles(...)

Vage Absicherungen. „Einige Fälle“, „verschiedene Gründe“, „behandelt Randfälle“, „usw.“ – nenne sie entweder oder lass den Satz weg.

Emojis. Verboten im Quellcode, einschließlich Kommentaren (Repos-weite Richtlinie).

Ad-hoc Abschnittsbanner (// ----- Hilfsfunktionen -----, // ==== TYPEN ====). Dieses Codebase hat keine // #region-Faltkonvention; füge keine Banner hinzu. Wenn eine Datei lang genug ist, dass du nach einem greifst, ist das ein Signal, die Datei zu teilen, nicht sie zu dekorieren.

Konventionen in diesem Codebase

JSDoc-Tags. @param name - Beschreibung, @returns und @throws geben den Vertrag an. Setze einen Typ in geschweifte Klammern (@returns {Promise<string>}) nur, wenn die Signatur allein mehrdeutig ist. Verwende @example mit einem umschlossenen ```js-Block für nicht offensichtliche Verwendung.

Querverweise. Verwende {@link Symbol} / {@linkcode Symbol} anstelle eines bloßen Namens, sodass eine Umbenennung die Referenz aktualisiert und Editoren zum Ziel springen können.

@internal. Markiert APIs, die nicht Teil der öffentlichen Oberfläche sind. Es ist nur eine Konvention – es gibt hier kein Typedoc oder api-extractor, um es zu entfernen – also dokumentiert es die Absicht, ersetzt aber keine Zugriffsmodifikatoren.

@deprecated. Gib die Migration an, dann den Entfernungshorizont:

/** @deprecated Verwende stattdessen die Instanzmethode `cookies.consume()`. Diese wird in Astro 7 entfernt */

Sage, was stattdessen verwendet werden soll, nicht nur, dass das Symbol veraltet ist. Diese zukunftsgerichtete Notiz ist Vertragsinformation, die der Leser benötigt, und keine verbotene Änderungshistorie-Erzählung.

TODO. Verwende // TODO: für aufgeschobene Arbeiten; verlinke ein Issue, wenn eines es verfolgt. Für Arbeiten, die auf ein Breaking-Change-Fenster warten, verwende das etablierte Idiom // TODO: remove in Astro <N>. Es gibt kein FIXME in diesem Codebase – führe es nicht ein.

Vorhandenen Code bearbeiten

• Bewahre vorhandene Kommentare. Wenn deine Änderung das Verhalten verändert, erweitere oder korrigiere den spezifischen Text – ersetze ihn niemals durch generischen Text. Das Löschen von mühsam erarbeitetem Kontext ist schlimmer, als einen leicht veralteten Kommentar zu hinterlassen.
• Wenn deine Änderung einen Kommentar falsch macht, korrigiere ihn im selben Diff. Ein veralteter Kommentar ist schlimmer als keiner.
• Passe die umgebende Dichte an. Ein stark dokumentiertes Modul verdient das gleiche Niveau bei neuen Elementen; überschwemme ein spärliches Modul nicht pauschal mit Kommentaren.

Selbstüberprüfung vor dem Abschluss

Nach Abschluss einer Aufgabe, die Kommentare berührt hat, lies nur die Kommentare in deinem Diff isoliert von den Code-Änderungen erneut:

1. Besteht jeder den Löschtest?
2. Bezieht sich einer auf das Gespräch, die Änderung selbst oder den Reviewer?
3. Hat jeder Workaround einen Link zu seinem Issue oder PR?
4. Würde ein Leser ohne Zugriff auf den Diff jeden verstehen?

Korrigiere oder lösche, was nicht besteht. Löschen ist der Standard; ein fehlender Kommentar ist billiger als ein irreführender.

Referenzen

• Diátaxis – das Framework hinter der obigen Aufteilung in Erklärung / Referenz / Begründung.
• packages/astro/src/core/errors/README.md – für @docs-markierte Fehlereinträge (Endbenutzer-Dokumentation).
• TSDoc – die Tag-Referenz für TypeScript-Doc-Kommentare.