Post on 20-Jun-2015
description
Leichtgewichtige API-Dokumentation –
Ein Paradoxon?
Jan Christian Krause
Developer Conference Hamburg
07. Septmember 2012
Seite 2
Seite 2 Jan Christian Krause
Agenda
Motivation
Metaphern
Stand der Kunst: API-Dokumentation
API-Doku mit thematischen Rastern
iDocIt! – Ein Werkzeug zur API-Dokumentation
Beispiel: eBay Trading API
Zusammenfassung / Diskussion
Seite 3
Seite 3 Jan Christian Krause
Aus meinen Projekterfahrungen …
public interface CustomerService {
/**
* Finds the customers for the given lastname.
*
* @param lastname
* The lastname to look for
* @return The found customers
*
* @throws Exception
* In case of an error
*/
public List<Customer> findCustomerByName(
String lastname) throws Exception;
}
Motivation
Seite 4
Seite 4 Jan Christian Krause
… resultierende Fragen
• Ist der Code die Dokumentation?
• Weshalb ist Dokumentieren so aufwändig?
Motivation
Seite 5
Seite 5 Jan Christian Krause
Vertrag
• Beschreibung der Dienstleistung der Operation
• Rechte und Pflichten des Konsumenten und
des Produzenten
Vertrag
Schnittstellenvertrag
(Spezifikation)
Implementierungsvertrag
(Dokumentation)
Metaphern
Seite 6
Seite 6 Jan Christian Krause
Stille und Rauschen
• Stille: Relevantes Charakteristikum der Operation,
das im Vertrag nicht erwähnt wird.
• Rauschen: Überflüssiger Vertragsbestandteil
Metaphern
Seite 7
Seite 7 Jan Christian Krause
Vertragsinhalte in der Praxis
• Vorgabe eines Rasters (z.B. Javadoc)
• Raster enthält öffentliche Signaturelemente
(z.B. Parameter, etc.), sowie Metadaten (z.B.
Autor, etc.)
• Natürlichsprachliche Kurzbeschreibung der
Operation
• Vor- und Nachbedingungen (selten)
Stand der Kunst: API-Dokumentation
Seite 8
Seite 8 Jan Christian Krause
Gefahr von Stille
Weitgehend standardisiertes und etabliertes
Vorgehensmodell
Breite Werkzeugpalette verfügbar
Seiteneffekte?
Vollständigkeit der Beschreibungen?
Spezifikationen (z.B. einer Rechenvorschrift)?
Nicht sichtbare „Parameter“ (z.B. in
Konfigurationsdateien)?
Stand der Kunst: API-Dokumentation
Seite 9
Seite 9 Jan Christian Krause
Gefahr von Rauschen (I)
Stand der Kunst: API-Dokumentation
Seite 10
Seite 10 Jan Christian Krause
Gefahr von Rauschen (II)
Stand der Kunst: API-Dokumentation
Seite 11
Seite 11 Jan Christian Krause
Gefahr von Rauschen (III)
Stand der Kunst: API-Dokumentation
Seite 12
Seite 12 Jan Christian Krause
Gefahr von Rauschen (IV)
Stand der Kunst: API-Dokumentation
Seite 13
Seite 13 Jan Christian Krause
Grundkonzept
• Operationsbezeichner enthalten ein Verb
• Das Verb hat eine Bedeutung.
• Die Bedeutung kann über Argumente
spezifiziert werden.
• Die Beschreibung der Argumente erfolgt an
der Operation (Lokalitätsprinzip).
API-Doku mit thematischen Rastern
Seite 14
Seite 14 Jan Christian Krause
Beispiel für ein thematisches Raster
Searching Operations
Description: Represents operations which fetch one or
more objects from a defined source. The
returned objects are identied by a
specified set of criteria.
Verbs: find, get, search, look
Mandatory Roles: OBJECT, COMPARISON, SOURCE
Optional Roles: ORDERING, ALGORITHM
API-Doku mit thematischen Rastern
Seite 15
Seite 15 Jan Christian Krause
Erkennung von Stille
API-Doku mit thematischen Rastern
Seite 16
Seite 16 Jan Christian Krause
Erkennung von Rauschen (I)
API-Doku mit thematischen Rastern
Seite 17
Seite 17 Jan Christian Krause
Erkennung von Rauschen (II)
API-Doku mit thematischen Rastern
Seite 18
Seite 18 Jan Christian Krause
Erkennung von Rauschen (III)
API-Doku mit thematischen Rastern
Seite 19
Seite 19 Jan Christian Krause
Detailliertes Beispiel
Searching Operation
A searching operation searches for one or many
OBJECTs at a SOURCE. The searched OBJECTs are
identified by one or many COMPARISONs or PRIMARY
KEYs. The number of found OBJECTs could be limited by
specifying a LIMIT. In case of many OBJECTs an
ORDERING defines their arrangement. The ALGORITHM
defines the way the OBJECTs are searched.
This category bases on the VerbNet classes Search-35.2
and obtain-13.5.2.
API-Doku mit thematischen Rastern
Seite 20
Seite 20 Jan Christian Krause
Weitere Beispiele für thematische Raster
• Converting Operations
• Mathematical Operations
• Sending Operations
AKRA arbeitet derzeit mit 22 thematischen
Rastern
API-Doku mit thematischen Rastern
Seite 21
Seite 21 Jan Christian Krause
Zusammenfassung (I)
Stille und Rauschen kann mit Hilfe
thematischer Raster vermieden werden
Thematische Raster helfen ebenfalls bei der
Definition von Operationen einer Schnittstelle
(z.B. bei der Bestimmung der Parameter)
Thematische Raster funktionieren ohne
Kenntnis von Quelltexten
API-Doku mit thematischen Rastern
Seite 22
Seite 22 Jan Christian Krause
Zusammenfassung (II)
Kardinalitäten thematischer Rollen nicht
ableitbar (z.B. Anzahl SOURCEs)
Qualität der Bezeichner determiniert Qualität
der Unterstützung
Thematische Raster müssen definiert werden
API-Doku mit thematischen Rastern
Seite 23
Seite 23 Jan Christian Krause
iDocIt! – Ein Werkzeug zur API-Dokumentation
• Editor zur Dokumentation
• Eclipse Plugin (Indigo 3.7)
• idocit.googlecode.com
• Unterstützt derzeit WSDL und Java
• Erweiterbar um weitere Programmier- /
Markupsprachen (als Plugins)
iDocIt!
Seite 24
Seite 24 Jan Christian Krause
Kurzbeschreibung
• Ebay bietet Web Service zur Integration von
Ebay-Diensten in Anwendungen
• Analysiert wird die Operation
getFeedback(...)
• Ziel: Ermittlung von Stille und Rauschen
• Nutzung von iDocIt! als Analyse-Werkzeug
Beispiel: Ebay Trading API
Seite 25
Seite 25 Jan Christian Krause
Ergebnisse – Stille:
• Sortierung der zurückgelieferten Bewertungen
ist nicht spezifiziert [them. Rolle ORDERING]
• Unterschiedliche Datenquellen (Sandbox-
und Produktivumgebung) sind nur
unzureichend dargestellt [them. Rolle
SOURCE]
• Berechnungsvorschrift für die Feedback-
Punktzahl ist nicht dokumentiert (findet sich
an anderer Stelle in der Ebay Online-Hilfe)
[them. Rolle FORMULA]
Beispiel: Ebay Trading API
Seite 26
Seite 26 Jan Christian Krause
Ergebnisse – Rauschen:
• Vermeidung von Redundanz durch Nutzung
der Rolle PRIMARY KEY für ID-Felder (z.B.
FeedbackID)
• Durch Anwendung des Lokalitätsprinzips bzgl.
Felddokumentation lässt sich viel Rauschen
der Kategorie 2 einsparen, z.B. bei Feld
DetailLevel.
Beispiel: Ebay Trading API
Seite 27
Seite 27 Jan Christian Krause
Zusammenfassung
• Thematische Raster können helfen Stille und
Rauschen zu vermeiden
• Voraussetzung sind präzise gewählte Verben
in den Operationsbezeichnern
• Kardinalitäten thematischer Rollen sind nicht
ableitbar
Diskussion
Seite 28
Seite 28 Jan Christian Krause
Ausblick
• Ausbau der Sammlung thematischer Raster
• Tiefere Integration von iDocIt! in die Eclipse-
Code-Editoren
• Studie zur Qualitätssteigerung durch
thematische Raster
Diskussion
Seite 29
Seite 29 Jan Christian Krause
Diskussion
Vielen Dank für Ihre Aufmerksamkeit.
Haben Sie Anmerkungen, Fragen oder Kritik?
Diskussion
Seite 30
Seite 30 Jan Christian Krause
Kontakt
Jan Christian Krause
Software-Entwickler
AKRA GmbH
Domstraße 17
20095 Hamburg
www.akra.de
Mail jan-christian.krause@akra.de
Büro +49 40 - 309 535 – 30
Twitter @iDocIt
Blog idocit.blogspot.de