Ein Stilleitfaden für API-Referenzen: eine Form für jeden Eintrag

Worum es geht

Ein Referenzeintrag beschreibt eine Funktion, einen Endpunkt, einen Typ oder eine Option. Ein Stilleitfaden für Referenzmaterial ist ein kurzes internes Dokument, das für jeden Eintrag die Abschnitte und ihre Reihenfolge, die Form des einleitenden Satzes und den Wortlaut wiederkehrender Angaben festlegt. Microsofts Referenzrichtlinie (zitiert) listet die Abschnitte eines Referenzartikels in fester Reihenfolge: Titel und Beschreibung, Deklaration oder Syntax, Parameter, Rückgabewert, Anmerkungen, Beispiel, Anforderungen und Siehe-auch, mit Ausnahmen oder Fehlercodes dort, wo das Element sie auslösen kann; jeder Parameter trägt seinen Datentyp und, wo angebracht, ob er erforderlich oder optional ist, und die Beschreibung darf den Elementnamen nicht bloss wiederholen. Googles Richtlinie für API-Referenzkommentare (zitiert) hält fest, dass nur der erste Satz einer Beschreibung in Zusammenfassungsabschnitten und Indizes erscheint, weshalb die wichtigste Information dorthin gehört, und dass eine Veraltungsmarkierung sagen muss, was stattdessen zu verwenden ist. OpenAPI (zitiert) trennt eine summary, eine kurze Aussage darüber, was eine Operation tut, von einer längeren description.

Warum es wichtig ist

Referenzmaterial wird nachschlagend gelesen, nicht der Reihe nach. Eine Person, die in einem Eintrag gelernt hat, wo der Rückgabewert steht, erwartet ihn im nächsten an derselben Stelle; ein Agent, der Parameter extrahiert, verlässt sich auf dieselbe Regelmässigkeit. Generierte Referenzen (aus Docstrings, OpenAPI, Doc-Kommentaren) übernehmen die Disziplin, die die Quelle hat, weshalb der Stilleitfaden an der Quelle angewendet wird.

So wird es angewendet

• Erster Satz: eine vollständige Aussage darüber, was die Sache tut, in der dritten Person, beginnend mit einem Verb („Gibt … zurück", „Erstellt …"), die allein in einem Index sinnvoll ist.
• Parameter: Name, Typ, erforderlich oder optional, Standardwert, erlaubter Bereich oder erlaubtes Format, und was an der Grenze geschieht. Ein Parameter ohne angegebenen Standardwert hat ein undokumentiertes Verhalten.
• Rückgabewert: Typ, Bedeutung, und die Fälle leer, null oder nicht gefunden.
• Fehler: eine Zeile pro Bedingung, in der Form „Bedingung: ausgelöster Fehler oder zurückgegebener Status"; auf das gemeinsame Fehlerformat verlinken.
• Anmerkungen: Reihenfolgegarantien, Idempotenz, Nebenwirkungen, Ratenbegrenzungen, Thread-Sicherheit. Nichts, was in ein Tutorial gehört.
• Beispiel: ein minimaler, lauffähiger Aufruf mit seiner Ausgabe; ihn wo möglich in der CI ausführen lassen.
• Veraltung: der Ersatz, die Version seit wann, und der Entfernungsplan, im ersten Satz.
• Terminologie: für jedes Konzept den vom Glossar bevorzugten Begriff verwenden und durchgehend dieselben Einheiten und Datumsformate.

Stolpersteine

Zusammenfassungen, die den Namen wiederholen („getUser: holt den Benutzer"). Die Implementierung statt des Vertrags zu beschreiben. Einschränkungen, die nur in Fliesstext stehen, den ein Validator anders durchsetzt. Beispiele, die nicht mehr laufen. Unterschiedliche Abschnittsreihenfolgen je Autorenschaft, was genau das Problem ist, das der Leitfaden beseitigen soll.