Your SlideShare is downloading. ×
Leichtgewichtige API-Dokumentation – Ein Paradoxon?
Upcoming SlideShare
Loading in...5
×

Thanks for flagging this SlideShare!

Oops! An error has occurred.

×
Saving this for later? Get the SlideShare app to save on your phone or tablet. Read anywhere, anytime – even offline.
Text the download link to your phone
Standard text messaging rates apply

Leichtgewichtige API-Dokumentation – Ein Paradoxon?

150
views

Published on

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.


0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
150
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

Report content
Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
No notes for slide

Transcript

  • 1. Leichtgewichtige API-Dokumentation – Ein Paradoxon? Jan Christian Krause Developer Conference Hamburg 07. Septmember 2012
  • 2. 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
  • 3. 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
  • 4. Motivation… resultierende Fragen • Ist der Code die Dokumentation? • Weshalb ist Dokumentieren so aufwändig? Jan Christian Krause Seite 4
  • 5. MetaphernVertrag • Beschreibung der Dienstleistung der Operation • Rechte und Pflichten des Konsumenten und des Produzenten Vertrag Schnittstellenvertrag Implementierungsvertrag (Spezifikation) (Dokumentation) Jan Christian Krause Seite 5
  • 6. MetaphernStille und Rauschen • Stille: Relevantes Charakteristikum der Operation, das im Vertrag nicht erwähnt wird. • Rauschen: Überflüssiger Vertragsbestandteil Jan Christian Krause Seite 6
  • 7. 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
  • 8. 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
  • 9. Stand der Kunst: API-DokumentationGefahr von Rauschen (I) Jan Christian Krause Seite 9
  • 10. Stand der Kunst: API-DokumentationGefahr von Rauschen (II) Jan Christian Krause Seite 10
  • 11. Stand der Kunst: API-DokumentationGefahr von Rauschen (III) Jan Christian Krause Seite 11
  • 12. Stand der Kunst: API-DokumentationGefahr von Rauschen (IV) Jan Christian Krause Seite 12
  • 13. 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
  • 14. 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
  • 15. API-Doku mit thematischen RasternErkennung von Stille Jan Christian Krause Seite 15
  • 16. API-Doku mit thematischen RasternErkennung von Rauschen (I) Jan Christian Krause Seite 16
  • 17. API-Doku mit thematischen RasternErkennung von Rauschen (II) Jan Christian Krause Seite 17
  • 18. API-Doku mit thematischen RasternErkennung von Rauschen (III) Jan Christian Krause Seite 18
  • 19. 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
  • 20. 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
  • 21. 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
  • 22. 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
  • 23. 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
  • 24. 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
  • 25. 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
  • 26. 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
  • 27. 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
  • 28. 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
  • 29. DiskussionDiskussion Vielen Dank für Ihre Aufmerksamkeit. Haben Sie Anmerkungen, Fragen oder Kritik? Jan Christian Krause Seite 29
  • 30. 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

×