SlideShare ist ein Scribd-Unternehmen logo
Leichtgewichtige API-Dokumentation –
           Ein Paradoxon?
            Jan Christian Krause
       Developer Conference Hamburg
           07. Septmember 2012
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
Motivation

Aus 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
Motivation

… resultierende Fragen




       • Ist der Code die Dokumentation?
       • Weshalb ist Dokumentieren so aufwändig?




                         Jan Christian Krause      Seite 4
Metaphern

Vertrag

      • Beschreibung der Dienstleistung der Operation

      • Rechte und Pflichten des Konsumenten und
        des Produzenten

                                    Vertrag


            Schnittstellenvertrag                     Implementierungsvertrag
               (Spezifikation)                           (Dokumentation)



                                    Jan Christian Krause                        Seite 5
Metaphern

Stille und Rauschen

      • Stille:
        Relevantes Charakteristikum der Operation,
        das im Vertrag nicht erwähnt wird.

      • Rauschen:
        Überflüssiger Vertragsbestandteil




                        Jan Christian Krause         Seite 6
Stand der Kunst: API-Dokumentation

Vertragsinhalte 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
Stand der Kunst: API-Dokumentation

Gefahr 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
Stand der Kunst: API-Dokumentation

Gefahr von Rauschen (I)




                              Jan Christian Krause   Seite 9
Stand der Kunst: API-Dokumentation

Gefahr von Rauschen (II)




                              Jan Christian Krause   Seite 10
Stand der Kunst: API-Dokumentation

Gefahr von Rauschen (III)




                               Jan Christian Krause   Seite 11
Stand der Kunst: API-Dokumentation

Gefahr von Rauschen (IV)




                              Jan Christian Krause   Seite 12
API-Doku mit thematischen Rastern

Grundkonzept

      • 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
API-Doku mit thematischen Rastern

Beispiel 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
API-Doku mit thematischen Rastern

Erkennung von Stille




                               Jan Christian Krause   Seite 15
API-Doku mit thematischen Rastern

Erkennung von Rauschen (I)




                               Jan Christian Krause   Seite 16
API-Doku mit thematischen Rastern

Erkennung von Rauschen (II)




                               Jan Christian Krause   Seite 17
API-Doku mit thematischen Rastern

Erkennung von Rauschen (III)




                               Jan Christian Krause   Seite 18
API-Doku mit thematischen Rastern

Detailliertes 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
API-Doku mit thematischen Rastern

Weitere Beispiele für thematische Raster

      • Converting Operations

      • Mathematical Operations

      • Sending Operations

       AKRA arbeitet derzeit mit 22 thematischen
        Rastern



                               Jan Christian Krause   Seite 20
API-Doku mit thematischen Rastern

Zusammenfassung (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
API-Doku mit thematischen Rastern

Zusammenfassung (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
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
Beispiel: Ebay Trading API

Kurzbeschreibung

       • 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
Beispiel: Ebay Trading API

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]

                             Jan Christian Krause   Seite 25
Beispiel: Ebay Trading API

Ergebnisse – 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
Diskussion

Zusammenfassung

      • 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
Diskussion

Ausblick

      • 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
Diskussion

Diskussion




            Vielen Dank für Ihre Aufmerksamkeit.
         Haben Sie Anmerkungen, Fragen oder Kritik?




                        Jan Christian Krause          Seite 29
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

Weitere ähnliche Inhalte

Andere mochten auch

Test Files
Test FilesTest Files
Test Files
nyler01
 
Dossier Bac Pro
Dossier Bac ProDossier Bac Pro
Dossier Bac Pro
youri59490
 
Los 10 mandamientos de la calidad
Los 10 mandamientos de la calidadLos 10 mandamientos de la calidad
Los 10 mandamientos de la calidad
Wilder Huamán Oscco
 
Sondage Twitter Careerssocgen Fev. 2010
Sondage Twitter Careerssocgen Fev. 2010Sondage Twitter Careerssocgen Fev. 2010
Sondage Twitter Careerssocgen Fev. 2010
Franck La Pinta
 
Mes chansons préférées, par Tamara
Mes chansons préférées, par  TamaraMes chansons préférées, par  Tamara
Mes chansons préférées, par Tamara
tambre
 
Emma hack
Emma hackEmma hack
PSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbH
PSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbHPSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbH
PSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbH
www.edv-werbeartikel.de GmbH
 
Tipos de computadoras
Tipos de computadorasTipos de computadoras
Tipos de computadoras
Shadowgts1
 
Blog ejemplos
Blog ejemplosBlog ejemplos
Blog ejemplos
Wilmer Campos Saavedra
 
Compromiso
CompromisoCompromiso
Compromiso
Yt Marin
 
Finca libre de brucelosisi
Finca libre de brucelosisiFinca libre de brucelosisi
Finca libre de brucelosisi
Luis Camues
 
Silence on joue !
Silence on joue !Silence on joue !
Silence on joue !
Julien Devriendt
 
Sensibiliser les lycéens roumains à la musique française
Sensibiliser  les  lycéens roumains à la musique française Sensibiliser  les  lycéens roumains à la musique française
Sensibiliser les lycéens roumains à la musique française
gbadau
 
Bahagi koko blog
Bahagi koko   blogBahagi koko   blog
Bahagi koko blog
wanroswandy
 
Patri.
Patri.Patri.
Patri.
School
 
Seminario Artritis Infecciosa
Seminario Artritis InfecciosaSeminario Artritis Infecciosa
Seminario Artritis Infecciosa
Alonso Custodio
 

Andere mochten auch (20)

Test Files
Test FilesTest Files
Test Files
 
Douaisis
DouaisisDouaisis
Douaisis
 
Dossier Bac Pro
Dossier Bac ProDossier Bac Pro
Dossier Bac Pro
 
E2 B2
E2  B2E2  B2
E2 B2
 
Los 10 mandamientos de la calidad
Los 10 mandamientos de la calidadLos 10 mandamientos de la calidad
Los 10 mandamientos de la calidad
 
Sondage Twitter Careerssocgen Fev. 2010
Sondage Twitter Careerssocgen Fev. 2010Sondage Twitter Careerssocgen Fev. 2010
Sondage Twitter Careerssocgen Fev. 2010
 
Mes chansons préférées, par Tamara
Mes chansons préférées, par  TamaraMes chansons préférées, par  Tamara
Mes chansons préférées, par Tamara
 
Emma hack
Emma hackEmma hack
Emma hack
 
PSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbH
PSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbHPSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbH
PSI 2016 Messe Neuheiten der EDV-Werbeartikel.de GmbH
 
Tipos de computadoras
Tipos de computadorasTipos de computadoras
Tipos de computadoras
 
Blog ejemplos
Blog ejemplosBlog ejemplos
Blog ejemplos
 
4-Cm12
4-Cm124-Cm12
4-Cm12
 
Compromiso
CompromisoCompromiso
Compromiso
 
Finca libre de brucelosisi
Finca libre de brucelosisiFinca libre de brucelosisi
Finca libre de brucelosisi
 
Silence on joue !
Silence on joue !Silence on joue !
Silence on joue !
 
Sensibiliser les lycéens roumains à la musique française
Sensibiliser  les  lycéens roumains à la musique française Sensibiliser  les  lycéens roumains à la musique française
Sensibiliser les lycéens roumains à la musique française
 
Bahagi koko blog
Bahagi koko   blogBahagi koko   blog
Bahagi koko blog
 
Monster
MonsterMonster
Monster
 
Patri.
Patri.Patri.
Patri.
 
Seminario Artritis Infecciosa
Seminario Artritis InfecciosaSeminario Artritis Infecciosa
Seminario Artritis Infecciosa
 

Ähnlich wie Leichtgewichtige API-Dokumentation – Ein Paradoxon?

Apache Solr und TYPO3 @ Frankfurt PHP usergroup 2011-01
Apache Solr und TYPO3 @  Frankfurt PHP usergroup 2011-01Apache Solr und TYPO3 @  Frankfurt PHP usergroup 2011-01
Apache Solr und TYPO3 @ Frankfurt PHP usergroup 2011-01
Ingo Renner
 
Debugging und Profiling
Debugging und ProfilingDebugging und Profiling
Debugging und Profiling
Sebastian Springer
 
Text Mining mit Python und PowerBI
Text Mining mit Python und PowerBIText Mining mit Python und PowerBI
Text Mining mit Python und PowerBI
Jens Albrecht
 
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“
hpaustria
 
SciflowWriter
SciflowWriterSciflowWriter
SciflowWriter
Michael Sievers
 
FileMaker Konferenz 2012 Lightning Presentation
FileMaker Konferenz 2012 Lightning PresentationFileMaker Konferenz 2012 Lightning Presentation
FileMaker Konferenz 2012 Lightning Presentation
Martin Brändle
 
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Spark Summit
 
C/ C++ for Notes & Domino Developers
C/ C++ for Notes & Domino DevelopersC/ C++ for Notes & Domino Developers
C/ C++ for Notes & Domino Developers
Ulrich Krause
 
Volltextsuche mit Lucene und Solr
Volltextsuche mit Lucene und SolrVolltextsuche mit Lucene und Solr
Volltextsuche mit Lucene und Solr
Thomas Koch
 
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...
Gregor Biswanger
 
Traumziel MV: Relaunch eines Tourismusportals mit Typo3 Extbase und Fluid
Traumziel MV:  Relaunch eines Tourismusportals mit Typo3 Extbase und FluidTraumziel MV:  Relaunch eines Tourismusportals mit Typo3 Extbase und Fluid
Traumziel MV: Relaunch eines Tourismusportals mit Typo3 Extbase und Fluid
Qbus Werbeagentur
 
Sonnenschein für ihre Website
Sonnenschein für ihre WebsiteSonnenschein für ihre Website
Sonnenschein für ihre Website
Olivier Dobberkau
 
[DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010
 [DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010 [DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010
[DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010
PROJECT CONSULT Unternehmensberatung Dr. Ulrich Kampffmeyer GmbH
 
Einstieg in Xamarin und Xamarin.Forms, DDC 2018
Einstieg in Xamarin und Xamarin.Forms, DDC 2018Einstieg in Xamarin und Xamarin.Forms, DDC 2018
Einstieg in Xamarin und Xamarin.Forms, DDC 2018
André Krämer
 
Eine Stunde was mit Api First!
Eine Stunde was mit Api First!Eine Stunde was mit Api First!
Eine Stunde was mit Api First!
JanWeinschenker
 
Enterprise JS
Enterprise JS Enterprise JS
Enterprise JS
Oliver Ochs
 
Bedeutungsorientierte Suche mit Sprachverstehen statt Stichwortsuche
Bedeutungsorientierte Suche mit Sprachverstehen statt StichwortsucheBedeutungsorientierte Suche mit Sprachverstehen statt Stichwortsuche
Bedeutungsorientierte Suche mit Sprachverstehen statt Stichwortsuche
SEMPRIA
 
Windows Powershell
Windows PowershellWindows Powershell
Windows Powershell
Thomas Wilhelm Wiefel
 
DSpace as publication platform
DSpace as publication platformDSpace as publication platform
DSpace as publication platform
redsys
 

Ähnlich wie Leichtgewichtige API-Dokumentation – Ein Paradoxon? (20)

Apache Solr und TYPO3 @ Frankfurt PHP usergroup 2011-01
Apache Solr und TYPO3 @  Frankfurt PHP usergroup 2011-01Apache Solr und TYPO3 @  Frankfurt PHP usergroup 2011-01
Apache Solr und TYPO3 @ Frankfurt PHP usergroup 2011-01
 
Debugging und Profiling
Debugging und ProfilingDebugging und Profiling
Debugging und Profiling
 
Amazon Web Services
Amazon Web ServicesAmazon Web Services
Amazon Web Services
 
Text Mining mit Python und PowerBI
Text Mining mit Python und PowerBIText Mining mit Python und PowerBI
Text Mining mit Python und PowerBI
 
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“
Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“Kennst du einUnternehmen, dass erfolgreichdie QS outtasked hat?“
Kennst du ein Unternehmen, dass erfolgreich die QS outtasked hat?“
 
SciflowWriter
SciflowWriterSciflowWriter
SciflowWriter
 
FileMaker Konferenz 2012 Lightning Presentation
FileMaker Konferenz 2012 Lightning PresentationFileMaker Konferenz 2012 Lightning Presentation
FileMaker Konferenz 2012 Lightning Presentation
 
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
Clickstream Analysis with Spark—Understanding Visitors in Realtime by Josef A...
 
C/ C++ for Notes & Domino Developers
C/ C++ for Notes & Domino DevelopersC/ C++ for Notes & Domino Developers
C/ C++ for Notes & Domino Developers
 
Volltextsuche mit Lucene und Solr
Volltextsuche mit Lucene und SolrVolltextsuche mit Lucene und Solr
Volltextsuche mit Lucene und Solr
 
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...
Kuck mal, Node.js! Einstieg für .NET Entwickler mit Visual Studio Code und Ty...
 
Traumziel MV: Relaunch eines Tourismusportals mit Typo3 Extbase und Fluid
Traumziel MV:  Relaunch eines Tourismusportals mit Typo3 Extbase und FluidTraumziel MV:  Relaunch eines Tourismusportals mit Typo3 Extbase und Fluid
Traumziel MV: Relaunch eines Tourismusportals mit Typo3 Extbase und Fluid
 
Sonnenschein für ihre Website
Sonnenschein für ihre WebsiteSonnenschein für ihre Website
Sonnenschein für ihre Website
 
[DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010
 [DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010 [DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010
[DE] Glossar zu Dokumenten-Technologien | PROJECT CONSULT | Hamburg 2010
 
Einstieg in Xamarin und Xamarin.Forms, DDC 2018
Einstieg in Xamarin und Xamarin.Forms, DDC 2018Einstieg in Xamarin und Xamarin.Forms, DDC 2018
Einstieg in Xamarin und Xamarin.Forms, DDC 2018
 
Eine Stunde was mit Api First!
Eine Stunde was mit Api First!Eine Stunde was mit Api First!
Eine Stunde was mit Api First!
 
Enterprise JS
Enterprise JS Enterprise JS
Enterprise JS
 
Bedeutungsorientierte Suche mit Sprachverstehen statt Stichwortsuche
Bedeutungsorientierte Suche mit Sprachverstehen statt StichwortsucheBedeutungsorientierte Suche mit Sprachverstehen statt Stichwortsuche
Bedeutungsorientierte Suche mit Sprachverstehen statt Stichwortsuche
 
Windows Powershell
Windows PowershellWindows Powershell
Windows Powershell
 
DSpace as publication platform
DSpace as publication platformDSpace as publication platform
DSpace as publication platform
 

Mehr von DeveloperConference

Survival of the fittest - Alexander Jäger
Survival of the fittest - Alexander JägerSurvival of the fittest - Alexander Jäger
Survival of the fittest - Alexander Jäger
DeveloperConference
 
Eine Website in einer Stunde mit TYPO3 bauen
Eine Website in einer Stunde mit TYPO3 bauenEine Website in einer Stunde mit TYPO3 bauen
Eine Website in einer Stunde mit TYPO3 bauen
DeveloperConference
 
Keynote: O PHP, Where Art Thou?
Keynote: O PHP, Where Art Thou?Keynote: O PHP, Where Art Thou?
Keynote: O PHP, Where Art Thou?
DeveloperConference
 
Eine Website in einer Stunde mit TYPO3 bauen, Gernot Ploiner
Eine Website in einer Stunde mit TYPO3 bauen, Gernot PloinerEine Website in einer Stunde mit TYPO3 bauen, Gernot Ploiner
Eine Website in einer Stunde mit TYPO3 bauen, Gernot Ploiner
DeveloperConference
 
Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"
Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"
Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"
DeveloperConference
 
Developer Conference Hamburg 2012
Developer Conference Hamburg 2012Developer Conference Hamburg 2012
Developer Conference Hamburg 2012
DeveloperConference
 

Mehr von DeveloperConference (8)

Survival of the fittest - Alexander Jäger
Survival of the fittest - Alexander JägerSurvival of the fittest - Alexander Jäger
Survival of the fittest - Alexander Jäger
 
Eine Website in einer Stunde mit TYPO3 bauen
Eine Website in einer Stunde mit TYPO3 bauenEine Website in einer Stunde mit TYPO3 bauen
Eine Website in einer Stunde mit TYPO3 bauen
 
Keynote: O PHP, Where Art Thou?
Keynote: O PHP, Where Art Thou?Keynote: O PHP, Where Art Thou?
Keynote: O PHP, Where Art Thou?
 
Ruby on Rails
Ruby on RailsRuby on Rails
Ruby on Rails
 
Eine Website in einer Stunde mit TYPO3 bauen, Gernot Ploiner
Eine Website in einer Stunde mit TYPO3 bauen, Gernot PloinerEine Website in einer Stunde mit TYPO3 bauen, Gernot Ploiner
Eine Website in einer Stunde mit TYPO3 bauen, Gernot Ploiner
 
Hdc2012 cordova-präsi
Hdc2012 cordova-präsiHdc2012 cordova-präsi
Hdc2012 cordova-präsi
 
Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"
Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"
Lutz Prechelt - Keynote: "Meine Plattform ist besser als Deine Plattform???"
 
Developer Conference Hamburg 2012
Developer Conference Hamburg 2012Developer Conference Hamburg 2012
Developer Conference Hamburg 2012
 

Leichtgewichtige API-Dokumentation – Ein Paradoxon?

  • 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. Motivation Aus 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. Metaphern Vertrag • Beschreibung der Dienstleistung der Operation • Rechte und Pflichten des Konsumenten und des Produzenten Vertrag Schnittstellenvertrag Implementierungsvertrag (Spezifikation) (Dokumentation) Jan Christian Krause Seite 5
  • 6. Metaphern Stille 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-Dokumentation Vertragsinhalte 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-Dokumentation Gefahr 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-Dokumentation Gefahr von Rauschen (I) Jan Christian Krause Seite 9
  • 10. Stand der Kunst: API-Dokumentation Gefahr von Rauschen (II) Jan Christian Krause Seite 10
  • 11. Stand der Kunst: API-Dokumentation Gefahr von Rauschen (III) Jan Christian Krause Seite 11
  • 12. Stand der Kunst: API-Dokumentation Gefahr von Rauschen (IV) Jan Christian Krause Seite 12
  • 13. API-Doku mit thematischen Rastern Grundkonzept • 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 Rastern Beispiel 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 Rastern Erkennung von Stille Jan Christian Krause Seite 15
  • 16. API-Doku mit thematischen Rastern Erkennung von Rauschen (I) Jan Christian Krause Seite 16
  • 17. API-Doku mit thematischen Rastern Erkennung von Rauschen (II) Jan Christian Krause Seite 17
  • 18. API-Doku mit thematischen Rastern Erkennung von Rauschen (III) Jan Christian Krause Seite 18
  • 19. API-Doku mit thematischen Rastern Detailliertes 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 Rastern Weitere 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 Rastern Zusammenfassung (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 Rastern Zusammenfassung (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 API Kurzbeschreibung • 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 API 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] Jan Christian Krause Seite 25
  • 26. Beispiel: Ebay Trading API Ergebnisse – 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. Diskussion Zusammenfassung • 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. Diskussion Ausblick • 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. Diskussion Diskussion 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