Vermeidung von Stille und Rauschen in
API-Dokumentation
Vortrag auf dem 250. Treffen der GI- / ACM- Regionalgruppe HH
Jan ...
Jan Christian Krause 224.06.11
Agenda
1) Motivation
2) Metaphern „Stille“ und „Rauschen“
3) State of the Art der API-Dokum...
Jan Christian Krause 324.06.11
?
Motivation (I)
„Der Code ist die Dokumentation!“
„Working Software over
comprehensive doc...
Jan Christian Krause 424.06.11
Motivation (II)
1)Welche Einflüsse determinieren den Zeitaufwand zur Quelltext -
Kommentier...
Jan Christian Krause 524.06.11
Metaphern „Stille“ und „Rauschen“
* Übertragen aus: Bertrand Meyer: „On Formalism in Specif...
Jan Christian Krause 624.06.11
State of the Art d. API-Doku. (I)
„[...] Rather, the architect should expose only what user...
Jan Christian Krause 724.06.11
State of the Art d. API-Doku. (II)
●
Vorgabe eines Rasters, welches auszufüllen ist (z.B. J...
Jan Christian Krause 824.06.11
State of the Art d. API-Doku. (III)
 Seiteneffekte?
 Vollständigkeit natürlichsprachliche...
Jan Christian Krause 924.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstelle...
Jan Christian Krause 1024.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstell...
Jan Christian Krause 1124.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstell...
Jan Christian Krause 1224.06.11
State of the Art d. API-Doku. (IV)
Beispiel für eine dokumentierte Operation:
Schnittstell...
Jan Christian Krause 1324.06.11
Dokumentation mit them. Rastern (I)
●
Beobachtung: Operationsbezeichner enthalten meist ei...
Jan Christian Krause 1424.06.11
Dokumentation mit them. Rastern (II)
Beispiel: them. Raster für to find
Name: Searching Op...
Jan Christian Krause 1524.06.11
Dokumentation mit them. Rastern (III)
Beispiel - Vermeidung von Stille:
Find
[OBJECT] [COM...
Jan Christian Krause 1624.06.11
Dokumentation mit them. Rastern (IV)
Beispiel - Vermeidung von Rauschen:
Parameter Dokumen...
Jan Christian Krause 1724.06.11
Dokumentation mit them. Rastern (IV)
Parameter Them. Rolle Dokumentation
customerId PRIMAR...
Jan Christian Krause 1824.06.11
Dokumentation mit them. Rastern (IV)
Parameter Them. Rolle Dokumentation
customerId PRIMAR...
Jan Christian Krause 1924.06.11
Dokumentation mit them. Rastern (V)
Zusammenfassung:
 Stille und Rauschen kann mit Hilfe ...
Jan Christian Krause 2024.06.11
Open Source Werkzeug „iDocIt“
●
Entstanden in der Bachelor-Arbeit von Dirk Meier-Eickhoff ...
Jan Christian Krause 2124.06.11
Fallbeispiel: Ebay Trading API (I)
Überblick:
●
Ebay bietet Web Service zur Integration vo...
Jan Christian Krause 2224.06.11
Fallbeispiel: Ebay Trading API (II)
Ergebnisse - Stille:
●
Sortierung der zurückgelieferte...
Jan Christian Krause 2324.06.11
Fallbeispiel: Ebay Trading API (III)
●
Vermeidung von Redundanz durch Nutzung der Rolle PR...
Jan Christian Krause 2424.06.11
Zusammenfassung und Ausblick
●
Thematische Raster können helfen Stille und Rauschen zu ver...
Jan Christian Krause 2524.06.11
Diskussion
Vielen Dank für Ihre Aufmerksamkeit.
Haben Sie Fragen, Anregungen oder
Kritik?
Nächste SlideShare
Wird geladen in …5
×

Vermeidung von Stille und Rauschen in API-Dokumentatio

108 Aufrufe

Veröffentlicht am

Mein Foliensatz zu meinem Vortrag auf dem 250. Treffen der GI-/ACM-Regionalgruppe Hamburg.

Veröffentlicht in: Software
  • Als Erste(r) kommentieren

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

Vermeidung von Stille und Rauschen in API-Dokumentatio

  1. 1. Vermeidung von Stille und Rauschen in API-Dokumentation Vortrag auf dem 250. Treffen der GI- / ACM- Regionalgruppe HH Jan Christian Krause (AKRA GmbH)
  2. 2. Jan Christian Krause 224.06.11 Agenda 1) Motivation 2) Metaphern „Stille“ und „Rauschen“ 3) State of the Art der API-Dokumentation 4) Dokumentation mit thematischen Rastern 5) Open Source Werkzeug „iDocIt!“ 6) Fallbeispiel: Ebay Trading API 7) Zusammenfassung und Ausblick Ziele dieses Vortrags:  Lücken in Doku-Ansätzen aufzeigen  Neues Doku-Verfahren vorstellen  Werkzeug iDocIt! demonstrieren Keine Ziele dieses Vortrags:  Detailbetrachtung von Doku-Tools  Det. Überblick über Doku-Ansätze
  3. 3. Jan Christian Krause 324.06.11 ? Motivation (I) „Der Code ist die Dokumentation!“ „Working Software over comprehensive documentation*.“  Quelltext-Dokumentation wird häufig stiefmütterlich gehandhabt  Eigene Beobachtung: Bedarf an „guter“ Dokumentation existiert * Entnommen aus dem Agile Manifesto (verfügbar unter http://agilemanifesto.org/)
  4. 4. Jan Christian Krause 424.06.11 Motivation (II) 1)Welche Einflüsse determinieren den Zeitaufwand zur Quelltext - Kommentierung? 2)Können diese Einflüsse durch Einsatz geeigneter Werkzeuge kompensiert werden? Übergeordnete Fragestellungen:
  5. 5. Jan Christian Krause 524.06.11 Metaphern „Stille“ und „Rauschen“ * Übertragen aus: Bertrand Meyer: „On Formalism in Specifications“, Vol. 3, no. 1. IEEE Software, 1985 Stille: Relevanter Aspekt der Operation, der in der Dokumentation nicht erwähnt wird Rauschen: Redundante, nicht aktuelle oder unnötig ausführliche Dokumentation zu einem Aspekt der Operation Definitionen:
  6. 6. Jan Christian Krause 624.06.11 State of the Art d. API-Doku. (I) „[...] Rather, the architect should expose only what users of an element [an API] need to know in order to interact [or communicate] with it. [...]“ Was sollte dokumentiert werden? [Clements et al., 2002], p. 226 „[...] Write down only those effects that are visible to a user [...]“ [Clements et al., 2002], p. 230 Quelle: P. Clements, F. Bachmann, L. Bass, D. Garlan, J. Ivers, R. Little et al., Documenting Software Architectures – Views and Beyond, Addison-Wesley Professional, 2002
  7. 7. Jan Christian Krause 724.06.11 State of the Art d. API-Doku. (II) ● Vorgabe eines Rasters, welches auszufüllen ist (z.B. Javadoc oder WSDL) ● Inhalte des Rasters sind öffentliche Signaturelemente einer Operation (z.B. Parameter, etc.), sowie Metadaten (z.B. Autor, etc.) ● Natürlichsprachliche Kurzbeschreibung dessen, was die Operation macht ● Vor- und Nachbedingungen (meiner Erfahrung eher selten) ● ... Dokumentation in der Praxis:
  8. 8. Jan Christian Krause 824.06.11 State of the Art d. API-Doku. (III)  Seiteneffekte?  Vollständigkeit natürlichsprachlicher Beschreibungen?  Spezifikationen (z.B. einer Rechenvorschrift)?  Leser-Zielgruppen?  Nicht sichtbare Parameter (z.B. in Konfigurationsdateien)?  ...  Weitgehend standardisiertes und etabliertes Vorgehensmodell  Breite Werkzeugpalette verfügbar Zusammenfassung: Gefahr von Stille
  9. 9. Jan Christian Krause 924.06.11 State of the Art d. API-Doku. (IV) Beispiel für eine dokumentierte Operation: Schnittstellenelement Dokumentation Schnittstelle: CustomerCareService Provides eletronical services of the customer care department. Operation: findCustomerById Returns the customer-record with the given id. If no record is found, the result will be NULL. Parameter: Integer customerId The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. Rückgabetyp: Customer The customer-record with the given id.
  10. 10. Jan Christian Krause 1024.06.11 State of the Art d. API-Doku. (IV) Beispiel für eine dokumentierte Operation: Schnittstellenelement Dokumentation Schnittstelle: CustomerCareService Provides eletronical services of the customer care department. Operation: findCustomerById Returns the customer-record with the given id. If no record is found, the result will be NULL. Parameter: Integer customerId The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. Rückgabetyp: Customer The customer-record with the given id. Redundanz (Rauschen der Kategorie 1)
  11. 11. Jan Christian Krause 1124.06.11 State of the Art d. API-Doku. (IV) Beispiel für eine dokumentierte Operation: Schnittstellenelement Dokumentation Schnittstelle: CustomerCareService Provides eletronical services of the customer care department. Operation: findCustomerById Returns the customer-record with the given id. If no record is found, the result will be NULL. Parameter: Integer customerId The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. Rückgabetyp: Customer The customer-record with the given id. Redundanz (Rauschen der Kategorie 1) Nicht problemrelevant (Rauschen der Kategorie 2)
  12. 12. Jan Christian Krause 1224.06.11 State of the Art d. API-Doku. (IV) Beispiel für eine dokumentierte Operation: Schnittstellenelement Dokumentation Schnittstelle: CustomerCareService Provides eletronical services of the customer care department. Operation: findCustomerById Returns the customer-record with the given id. If no record is found, the result will be NULL. Parameter: Integer customerId The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. Rückgabetyp: Customer The customer-record with the given id. Redundanz (Rauschen der Kategorie 1) Nicht problemrelevant (Rauschen der Kategorie 2) Gefahr von Rauschen Veraltete Angaben (Rauschen der Kategorie 3)
  13. 13. Jan Christian Krause 1324.06.11 Dokumentation mit them. Rastern (I) ● Beobachtung: Operationsbezeichner enthalten meist ein Verb ● Ein Verb hat eine Bedeutung, die durch zusätzliche Argumente (thematische Rollen) weiter spezifiziert werden kann ● Die Zuordnung von möglichen Argumenten zu einem Verb erfolgt über ein thematisches Raster Grundkonzept:
  14. 14. Jan Christian Krause 1424.06.11 Dokumentation mit them. Rastern (II) Beispiel: them. Raster für to find Name: Searching Operations Description: Represents operations which fetch one or more objects from a defined source. The returned objects are identified by a specified set of criteria. Verbs: find, get, search, look Mandatory Roles: OBJECT, COMPARISON, SOURCE Optional Roles: ORDERING, ALGORITHM
  15. 15. Jan Christian Krause 1524.06.11 Dokumentation mit them. Rastern (III) Beispiel - Vermeidung von Stille: Find [OBJECT] [COMPARISON] [SOURCE] Find [OBJECT Customer] [COMPARISON customerId] [SOURCE ???]
  16. 16. Jan Christian Krause 1624.06.11 Dokumentation mit them. Rastern (IV) Beispiel - Vermeidung von Rauschen: Parameter Dokumentation customerId The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. Parameter Them. Rolle Dokumentation customerId PRIMARY KEY The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. 1. Thematische Rolle zuordnen
  17. 17. Jan Christian Krause 1724.06.11 Dokumentation mit them. Rastern (IV) Parameter Them. Rolle Dokumentation customerId PRIMARY KEY The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. Parameter Them. Rolle Dokumentation customerId PRIMARY KEY The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. 2. Rauschen erkennen Beispiel - Vermeidung von Rauschen:
  18. 18. Jan Christian Krause 1824.06.11 Dokumentation mit them. Rastern (IV) Parameter Them. Rolle Dokumentation customerId PRIMARY KEY The id of the customer to look for. Only values greater or equal to zero are valid. NULL is not permitted here. You can pass NULL only as parameter to the createCustomer-operation of this interface. Beispiel - Vermeidung von Rauschen: 3. Rauschen entfernen Parameter Them. Rolle Dokumentation customerId PRIMARY KEY NULL is not permitted here.
  19. 19. Jan Christian Krause 1924.06.11 Dokumentation mit them. Rastern (V) Zusammenfassung:  Stille und Rauschen kann mit Hilfe thematischer Raster vermieden werden  Them. Raster helfen ebenfalls bei der Definition von Operationen einer Schnittstelle (z.B. bei der Bestimmung der Parameter)  Them. Raster funktionieren ohne Kenntnis von Quelltexten  Kardinalitäten thematischer Rollen nicht ableitbar (z.B. Anzahl SOURCEs)  Qualität der Bezeichner determiniert Qualität der Unterstützung  Them. Raster müssen definiert werden  iDocIt! Bietet 19 Default-Raster
  20. 20. Jan Christian Krause 2024.06.11 Open Source Werkzeug „iDocIt“ ● Entstanden in der Bachelor-Arbeit von Dirk Meier-Eickhoff (AKRA GmbH) ● Eclipse Plugin (Helios 3.6) ● Open Source-Projekt bei Google Code (http://code.google.com/p/idocit/) ● Unterstützt derzeit WSDL und Java ● Erstes Release: 01.07.11 (geplant) Kurzbeschreibung: ● Editor zur Dokumentation mit them. Rollen und Rastern ● Anzeige passender them. Raster pro Operation ● HTML-Export der Dokumentation ● Erweiterbar um weitere Programmier- / Markupsprachen (als Plugins) Features:
  21. 21. Jan Christian Krause 2124.06.11 Fallbeispiel: Ebay Trading API (I) Überblick: ● 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
  22. 22. Jan Christian Krause 2224.06.11 Fallbeispiel: Ebay Trading API (II) 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]
  23. 23. Jan Christian Krause 2324.06.11 Fallbeispiel: Ebay Trading API (III) ● 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. Ergebnisse - Rauschen:
  24. 24. Jan Christian Krause 2424.06.11 Zusammenfassung und Ausblick ● 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 ● AKRA sammelt Erfahrungen mit diesem Verfahren in mehreren Projekten ● Offen bleibt: wie viel Dokumentation schafft wirklichen Mehrwert? Zusammenfassung: Ausblick: ● Weiterentwicklung von iDocIt! (Usability, Stabilität, etc.) ● Definition domänenspezifischer thematischer Raster ● Nutzung der Erkenntnisse im Bereich der Workflow-Modellierung ● Dokumentation von Klassenmodellen mithilfe them. Rollen
  25. 25. Jan Christian Krause 2524.06.11 Diskussion Vielen Dank für Ihre Aufmerksamkeit. Haben Sie Fragen, Anregungen oder Kritik?

×