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

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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. 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. Jan Christian Krause 2524.06.11
Diskussion
Vielen Dank für Ihre Aufmerksamkeit.
Haben Sie Fragen, Anregungen oder
Kritik?