Leichtgewichtige API Dokumentation

30
Leichtgewichtige API-Dokumentation Ein Paradoxon? Jan Christian Krause Developer Conference Hamburg 07. Septmember 2012

description

Vortrag auf der Developer Conference Hamburg vom 07.09.2012

Transcript of Leichtgewichtige API Dokumentation

Page 1: Leichtgewichtige API Dokumentation

Leichtgewichtige API-Dokumentation –

Ein Paradoxon?

Jan Christian Krause

Developer Conference Hamburg

07. Septmember 2012

Page 2: Leichtgewichtige API Dokumentation

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

Page 3: Leichtgewichtige API Dokumentation

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

Page 4: Leichtgewichtige API Dokumentation

Seite 4

Seite 4 Jan Christian Krause

… resultierende Fragen

• Ist der Code die Dokumentation?

• Weshalb ist Dokumentieren so aufwändig?

Motivation

Page 5: Leichtgewichtige API Dokumentation

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

Page 6: Leichtgewichtige API Dokumentation

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

Page 7: Leichtgewichtige API Dokumentation

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

Page 8: Leichtgewichtige 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

Page 9: Leichtgewichtige API Dokumentation

Seite 9

Seite 9 Jan Christian Krause

Gefahr von Rauschen (I)

Stand der Kunst: API-Dokumentation

Page 10: Leichtgewichtige API Dokumentation

Seite 10

Seite 10 Jan Christian Krause

Gefahr von Rauschen (II)

Stand der Kunst: API-Dokumentation

Page 11: Leichtgewichtige API Dokumentation

Seite 11

Seite 11 Jan Christian Krause

Gefahr von Rauschen (III)

Stand der Kunst: API-Dokumentation

Page 12: Leichtgewichtige API Dokumentation

Seite 12

Seite 12 Jan Christian Krause

Gefahr von Rauschen (IV)

Stand der Kunst: API-Dokumentation

Page 13: Leichtgewichtige 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

Page 14: Leichtgewichtige API Dokumentation

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

Page 15: Leichtgewichtige API Dokumentation

Seite 15

Seite 15 Jan Christian Krause

Erkennung von Stille

API-Doku mit thematischen Rastern

Page 16: Leichtgewichtige API Dokumentation

Seite 16

Seite 16 Jan Christian Krause

Erkennung von Rauschen (I)

API-Doku mit thematischen Rastern

Page 17: Leichtgewichtige API Dokumentation

Seite 17

Seite 17 Jan Christian Krause

Erkennung von Rauschen (II)

API-Doku mit thematischen Rastern

Page 18: Leichtgewichtige API Dokumentation

Seite 18

Seite 18 Jan Christian Krause

Erkennung von Rauschen (III)

API-Doku mit thematischen Rastern

Page 19: Leichtgewichtige API Dokumentation

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

Page 20: Leichtgewichtige API Dokumentation

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

Page 21: Leichtgewichtige API Dokumentation

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

Page 22: Leichtgewichtige API Dokumentation

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

Page 23: Leichtgewichtige API Dokumentation

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!

Page 24: Leichtgewichtige API Dokumentation

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

Page 25: Leichtgewichtige API Dokumentation

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

Page 26: Leichtgewichtige API Dokumentation

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

Page 27: Leichtgewichtige API Dokumentation

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

Page 28: Leichtgewichtige API Dokumentation

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

Page 29: Leichtgewichtige API Dokumentation

Seite 29

Seite 29 Jan Christian Krause

Diskussion

Vielen Dank für Ihre Aufmerksamkeit.

Haben Sie Anmerkungen, Fragen oder Kritik?

Diskussion

Page 30: Leichtgewichtige API Dokumentation

Seite 30

Seite 30 Jan Christian Krause

Kontakt

Jan Christian Krause

Software-Entwickler

AKRA GmbH

Domstraße 17

20095 Hamburg

www.akra.de

Mail [email protected]

Büro +49 40 - 309 535 – 30

Twitter @iDocIt

Blog idocit.blogspot.de