• Share
  • Email
  • Embed
  • Like
  • Save
  • Private Content
Leichtgewichtige API-Dokumentation – Ein Paradoxon?
 

Leichtgewichtige API-Dokumentation – Ein Paradoxon?

on

  • 231 views

Bei der Erstellung von API-Dokumentation besteht die Gefahr, dass relevante Informationen fehlen und irrelevante enthalten sind. Das Lesen dieser Art von Dokumentation ist aufwändig, u.U. nicht ...

Bei der Erstellung von API-Dokumentation besteht die Gefahr, dass relevante Informationen fehlen und irrelevante enthalten sind. Das Lesen dieser Art von Dokumentation ist aufwändig, u.U. nicht zielführend und kostet daher unnötig Zeit – und zwar für Autor und Leser. Dieser Vortrag diskutiert Ursachen dafür und zeigt, wie Lücken und irrelevante Aspekte in API-Dokumentation erkannt und vermieden werden können. Auf diese Weise kann die Pflege und Nutzung von API-Dokumentation trotz eines stressigen Projektalltags möglich werden.

Statistics

Views

Total Views
231
Views on SlideShare
231
Embed Views
0

Actions

Likes
0
Downloads
0
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 – Ein Paradoxon? Leichtgewichtige API-Dokumentation – Ein Paradoxon? 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