Leichtgewichtige API-Dokumentation –           Ein Paradoxon?            Jan Christian Krause       Developer Conference H...
Agenda    Motivation    Metaphern    Stand der Kunst: API-Dokumentation    API-Doku mit thematischen Rastern    iDocIt! – ...
MotivationAus meinen Projekterfahrungen …       public interface CustomerService {        /**         * Finds the customer...
Motivation… resultierende Fragen       • Ist der Code die Dokumentation?       • Weshalb ist Dokumentieren so aufwändig?  ...
MetaphernVertrag      • Beschreibung der Dienstleistung der Operation      • Rechte und Pflichten des Konsumenten und     ...
MetaphernStille und Rauschen      • Stille:        Relevantes Charakteristikum der Operation,        das im Vertrag nicht ...
Stand der Kunst: API-DokumentationVertragsinhalte in der Praxis      • Vorgabe eines Rasters (z.B. Javadoc)      • Raster ...
Stand der Kunst: API-DokumentationGefahr von Stille       Weitgehend standardisiertes und etabliertes        Vorgehensmod...
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 Bede...
API-Doku mit thematischen RasternBeispiel für ein thematisches Raster Searching Operations Description:          Represent...
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 o...
API-Doku mit thematischen RasternWeitere Beispiele für thematische Raster      • Converting Operations      • Mathematical...
API-Doku mit thematischen RasternZusammenfassung (I)       Stille und Rauschen kann mit Hilfe        thematischer Raster ...
API-Doku mit thematischen RasternZusammenfassung (II)       Kardinalitäten thematischer Rollen nicht        ableitbar (z....
iDocIt!iDocIt! – Ein Werkzeug zur API-Dokumentation          • Editor zur Dokumentation          • Eclipse Plugin (Indigo ...
Beispiel: Ebay Trading APIKurzbeschreibung       • Ebay bietet Web Service zur Integration von         Ebay-Diensten in An...
Beispiel: Ebay Trading APIErgebnisse – Stille:       • Sortierung der zurückgelieferten Bewertungen         ist nicht spez...
Beispiel: Ebay Trading APIErgebnisse – Rauschen:       • Vermeidung von Redundanz durch Nutzung         der Rolle PRIMARY ...
DiskussionZusammenfassung      • Thematische Raster können helfen Stille und        Rauschen zu vermeiden      • Vorausset...
DiskussionAusblick      • Ausbau der Sammlung thematischer Raster      • Tiefere Integration von iDocIt! in die Eclipse-  ...
DiskussionDiskussion            Vielen Dank für Ihre Aufmerksamkeit.         Haben Sie Anmerkungen, Fragen oder Kritik?   ...
Kontakt          Jan Christian Krause          Software-Entwickler          AKRA GmbH          Domstraße 17          20095...
Nächste SlideShare
Wird geladen in …5
×

Leichtgewichtige API-Dokumentation – Ein Paradoxon?

341 Aufrufe

Veröffentlicht am

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 Kommentare
0 Gefällt mir
Statistik
Notizen
  • Als Erste(r) kommentieren

  • Gehören Sie zu den Ersten, denen das gefällt!

Keine Downloads
Aufrufe
Aufrufe insgesamt
341
Auf SlideShare
0
Aus Einbettungen
0
Anzahl an Einbettungen
2
Aktionen
Geteilt
0
Downloads
0
Kommentare
0
Gefällt mir
0
Einbettungen 0
Keine Einbettungen

Keine Notizen für die Folie

Leichtgewichtige API-Dokumentation – Ein Paradoxon?

  1. 1. Leichtgewichtige API-Dokumentation – Ein Paradoxon? Jan Christian Krause Developer Conference Hamburg 07. Septmember 2012
  2. 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. 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. 4. Motivation… resultierende Fragen • Ist der Code die Dokumentation? • Weshalb ist Dokumentieren so aufwändig? Jan Christian Krause Seite 4
  5. 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. 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. 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. 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. 9. Stand der Kunst: API-DokumentationGefahr von Rauschen (I) Jan Christian Krause Seite 9
  10. 10. Stand der Kunst: API-DokumentationGefahr von Rauschen (II) Jan Christian Krause Seite 10
  11. 11. Stand der Kunst: API-DokumentationGefahr von Rauschen (III) Jan Christian Krause Seite 11
  12. 12. Stand der Kunst: API-DokumentationGefahr von Rauschen (IV) Jan Christian Krause Seite 12
  13. 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. 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. 15. API-Doku mit thematischen RasternErkennung von Stille Jan Christian Krause Seite 15
  16. 16. API-Doku mit thematischen RasternErkennung von Rauschen (I) Jan Christian Krause Seite 16
  17. 17. API-Doku mit thematischen RasternErkennung von Rauschen (II) Jan Christian Krause Seite 17
  18. 18. API-Doku mit thematischen RasternErkennung von Rauschen (III) Jan Christian Krause Seite 18
  19. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 29. DiskussionDiskussion Vielen Dank für Ihre Aufmerksamkeit. Haben Sie Anmerkungen, Fragen oder Kritik? Jan Christian Krause Seite 29
  30. 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

×