Читать книгу API-Design - Kai Spichale - Страница 42

Nachdem die Klassen und Interfaces der zu entwerfenden API mithilfe der Codebeispiele identifiziert worden sind, könnte eine formale Spezifikation erstellt werden. API-Spezifikationen dieser Art werden beispielsweise im Rahmen des Java Community Process (JCP) erarbeitet, um neue Sprachelemente aufzunehmen, aber auch APIs zu erweitern oder zu verändern. Die Spezifikationen definieren die Konzepte der API und die Anforderungen an Implementierungen. Eine textuelle Spezifikation kann durch ein detailliertes JavaDoc vervollständigt werden. Darin werden konkrete Packages, Interfaces, Klassen etc. genannt und beschrieben. Weitere Details zu JavaDoc finden Sie in Kapitel 12.

Prinzipiell können Sie eine API-Spezifikation in folgende Abschnitte gliedern:

Allgemeine Spezifikation

 Auf dieser Ebene können Eigenschaften spezifiziert werden, die für die gesamte API gültig sind. Beispielsweise kann festlegt werden, dass alle Objekte Thread-sicher sind. Abweichungen werden explizit angegeben. Ein anderes Beispiel ist der Umgang mit Unchecked Exceptions.

Package-Spezifikation

 Diese Angaben sind gültig für alle Elemente innerhalb eines Packages. Der Zweck des Packages sollte kurz und präzise beschrieben sein. Verweise auf andere Dokumente können hier ebenfalls eingefügt werden.

Klassen- und Interface-Spezifikation

 Dieser Abschnitt beginnt stets mit einer kurzen und präzisen Beschreibung des Objektes. Es folgen Angaben zu Thread-Sicherheit, Zustand (Immutability), Serialisierung, erlaubte Implementierungsvarianten, eventuelle Hardwareabhängigkeiten, Sicherheitseinschränkungen und Verweise auf andere Dokumente.

Feldspezifikation

 Zur Spezifikation eines Feldes gehört dessen Bedeutung, Wertebereich und eine Aussage, ob das Feld null sein könnte.

Methoden- und Konstruktorspezifikation

 Das erwartete Verhalten der Methode ist in jedem Fall anzugeben. Falls der Aufruf der Methode den Zustand des Objektes ändert, sollte ebenfalls die Zustandsänderung beschrieben werden. Weitere Angaben umfassen Bedeutung und Wertebereiche der Parameter, null-Parameter, mögliche Rückgabewerte, null-Rückgaben, erlaubte Implementierungsvarianten, Sicherheitseinschränkungen und Exceptions. Um das Verhalten der Methode korrekt beschreiben zu können, müssen häufig auch Algorithmen beschrieben werden.

Der Teufel steckt häufig im Detail, deswegen kann sich eine aufwendige Dokumentation gerade für veröffentlichte APIs lohnen. Vergessen Sie jedoch nicht zu beschreiben, wie die einzelnen Objekte im Kontext verwendet werden sollen. Typischerweise enthalten JSR-Spezifikationen (Java Specification Request) auch Beispiele, um die Funktionsweise zu verdeutlichen.