• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Leichtgewichtige API Dokumentation
 

Leichtgewichtige API Dokumentation

on

  • 326 views

Vortrag auf der Developer Conference Hamburg vom 07.09.2012

Vortrag auf der Developer Conference Hamburg vom 07.09.2012

Statistics

Views

Total Views
326
Views on SlideShare
326
Embed Views
0

Actions

Likes
0
Downloads
3
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as Adobe PDF

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    Leichtgewichtige API Dokumentation Leichtgewichtige API Dokumentation Presentation Transcript

    • Leichtgewichtige API-Dokumentation – Ein Paradoxon? Jan Christian Krause Developer Conference Hamburg 07. Septmember 2012
    • 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 Jan Christian Krause Seite 2
    • MotivationAus 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; } Jan Christian Krause Seite 3
    • Motivation… resultierende Fragen • Ist der Code die Dokumentation? • Weshalb ist Dokumentieren so aufwändig? Jan Christian Krause Seite 4
    • MetaphernVertrag • Beschreibung der Dienstleistung der Operation • Rechte und Pflichten des Konsumenten und des Produzenten Vertrag Schnittstellenvertrag Implementierungsvertrag (Spezifikation) (Dokumentation) Jan Christian Krause Seite 5
    • MetaphernStille und Rauschen • Stille: Relevantes Charakteristikum der Operation, das im Vertrag nicht erwähnt wird. • Rauschen: Überflüssiger Vertragsbestandteil Jan Christian Krause Seite 6
    • Stand der Kunst: API-DokumentationVertragsinhalte 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) Jan Christian Krause Seite 7
    • Stand der Kunst: API-DokumentationGefahr 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)? Jan Christian Krause Seite 8
    • Stand der Kunst: API-DokumentationGefahr von Rauschen (I) Jan Christian Krause Seite 9
    • Stand der Kunst: API-DokumentationGefahr von Rauschen (II) Jan Christian Krause Seite 10
    • Stand der Kunst: API-DokumentationGefahr von Rauschen (III) Jan Christian Krause Seite 11
    • Stand der Kunst: API-DokumentationGefahr von Rauschen (IV) Jan Christian Krause Seite 12
    • API-Doku mit thematischen RasternGrundkonzept • 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). Jan Christian Krause Seite 13
    • API-Doku mit thematischen RasternBeispiel 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 Jan Christian Krause Seite 14
    • API-Doku mit thematischen RasternErkennung von Stille Jan Christian Krause Seite 15
    • API-Doku mit thematischen RasternErkennung von Rauschen (I) Jan Christian Krause Seite 16
    • API-Doku mit thematischen RasternErkennung von Rauschen (II) Jan Christian Krause Seite 17
    • API-Doku mit thematischen RasternErkennung von Rauschen (III) Jan Christian Krause Seite 18
    • API-Doku mit thematischen RasternDetailliertes 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. Jan Christian Krause Seite 19
    • API-Doku mit thematischen RasternWeitere Beispiele für thematische Raster • Converting Operations • Mathematical Operations • Sending Operations  AKRA arbeitet derzeit mit 22 thematischen Rastern Jan Christian Krause Seite 20
    • API-Doku mit thematischen RasternZusammenfassung (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 Jan Christian Krause Seite 21
    • API-Doku mit thematischen RasternZusammenfassung (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 Jan Christian Krause Seite 22
    • iDocIt!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) Jan Christian Krause Seite 23
    • Beispiel: Ebay Trading APIKurzbeschreibung • 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 Jan Christian Krause Seite 24
    • Beispiel: Ebay Trading APIErgebnisse – 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] Jan Christian Krause Seite 25
    • Beispiel: Ebay Trading APIErgebnisse – 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. Jan Christian Krause Seite 26
    • DiskussionZusammenfassung • 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 Jan Christian Krause Seite 27
    • DiskussionAusblick • Ausbau der Sammlung thematischer Raster • Tiefere Integration von iDocIt! in die Eclipse- Code-Editoren • Studie zur Qualitätssteigerung durch thematische Raster Jan Christian Krause Seite 28
    • DiskussionDiskussion Vielen Dank für Ihre Aufmerksamkeit. Haben Sie Anmerkungen, Fragen oder Kritik? Jan Christian Krause Seite 29
    • 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 Jan Christian Krause Seite 30