Referenzdokumentation
Version: 2.0 · Stand: 2026-07-04 · Struktureller Bezug: Microsoft Writing Style Guide – Reference documentation (CC BY 4.0)
Referenzdokumentation beschreibt die Programmierelemente einer Bibliothek, API oder Sprache. Konsistenz ist hier entscheidend: einheitlicher Aufbau, vorhersehbare Überschriften und gleichbleibende Formulierungen helfen, schnell das Gesuchte zu finden.
Artikeltitel
Der Titel nennt das Element und seine Art (Klasse, Methode, Eigenschaft, Ereignis). Bei Namensgleichheit ein unterscheidendes Merkmal ergänzen (übergeordnetes Element, Produkt).
Beispiel
- Encrypt (Methode), SymmetricEncryptionExtensions.Encrypt (Methode)
Bestandteile eines Referenzartikels
| Abschnitt | Inhalt |
|---|---|
| Titel und Beschreibung | Elementname und ein bis zwei knappe Sätze dazu, was das Element bewirkt – ohne den Namen bloß zu wiederholen. |
| Deklaration/Syntax | Die Code-Signatur; bei mehreren Sprachen je Sprache. |
| Parameter | Je Parameter: Beschreibung, Datentyp, ob erforderlich/optional, Ein-/Ausgabe. Bei sicherheitsrelevanten Parametern die zulässigen Werte und Folgen benennen. |
| Rückgabewert | Beschreibung und Datentyp; bei booleschem Wert die geprüfte Bedingung. |
| Bemerkungen | Zusätzliche, nicht aus der Signatur ersichtliche Hinweise – Funktionsweise, Sicherheitshinweise, Fallstricke. |
| Beispiel | Codebeispiel zur Verwendung (siehe Codebeispiele). |
| Anforderungen/Gilt für | Plattform-, Sprach- oder Normanforderungen. |
| Ausnahmen | Auslösbare Ausnahmen/Fehler und ihre Bedingungen. |
| Siehe auch | Verweise auf verwandte Elemente. |
Aus Code generierte Dokumentation prüfen
Wird die Referenz aus Quellcode-Kommentaren generiert, muss die fachliche Eignung der Kommentare geprüft werden: fehlende kundenrelevante Details ergänzen, interne Implementierungsdetails entfernen. Ein guter Kommentar erklärt das Warum – Zweck, Annahmen, Einschränkungen, Sicherheitsaspekte –, nicht nur das Was.
Redaktionsleitfaden von The White Knight Labs. Aufbau nach dem Microsoft Writing Style Guide (© Microsoft Corporation, CC BY 4.0); Inhalte für den deutschsprachigen Raum eigenständig erarbeitet. Sprachregeln nach amtlicher deutscher Rechtschreibung, Duden und DIN 5008.