vermeidung von stille und rauschen in api-dokumentatio

Vermeidung von Stille und Rauschen in API-Dokumentation

Vortrag auf dem 250. Treffen der GI- / ACM- Regionalgruppe HH

Jan Christian Krause (AKRA GmbH)

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


?

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/)


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:


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:


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


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:


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 vonStille


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.







Parameter:



Redundanz (Rauschen der Kategorie 1)







Parameter:



Redundanz (Rauschen der Kategorie 1) Nicht problemrelevant (Rauschen der Kategorie 2)







Parameter:



Redundanz (Rauschen der Kategorie 1) Nicht problemrelevant (Rauschen der Kategorie 2)

Gefahr vonRauschen

Veraltete Angaben (Rauschen der Kategorie 3)


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:


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


Dokumentation mit them. Rastern (III)

Beispiel - Vermeidung von Stille:

Find [OBJECT] [COMPARISON] [SOURCE]

Find [OBJECT Customer] [COMPARISON customerId] [SOURCE ???]


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







2. Rauschen erkennen







3. Rauschen entfernen


customerId PRIMARY KEY NULL is not permitted here.


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


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:

http://code.google.com/p/idocit/


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


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]


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:


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


Diskussion

Vielen Dank für Ihre Aufmerksamkeit.

Haben Sie Fragen, Anregungen oder Kritik?