• Save
ESEconf2011 - Arrenbrecht Peter: "Literate Testing: Stimmige API's machen mehr Spass"
Upcoming SlideShare
Loading in...5
×
 

ESEconf2011 - Arrenbrecht Peter: "Literate Testing: Stimmige API's machen mehr Spass"

on

  • 505 views

 

Statistics

Views

Total Views
505
Views on SlideShare
505
Embed Views
0

Actions

Likes
0
Downloads
0
Comments
0

0 Embeds 0

No embeds

Accessibility

Categories

Upload Details

Uploaded via as OpenOffice

Usage Rights

© All Rights Reserved

Report content

Flagged as inappropriate Flag as inappropriate
Flag as inappropriate

Select your reason for flagging this presentation as inappropriate.

Cancel
  • Full Name Full Name Comment goes here.
    Are you sure you want to
    Your message goes here
    Processing…
Post Comment
Edit your comment

    ESEconf2011 - Arrenbrecht Peter: "Literate Testing: Stimmige API's machen mehr Spass" ESEconf2011 - Arrenbrecht Peter: "Literate Testing: Stimmige API's machen mehr Spass" Presentation Transcript

      • “Stimmige APIs kosten weniger.” Peter Arrenbrecht
      • codewise.ch @parrenbrecht
      Literate Testing
    • Wir alle designen APIs
        Prüft Verbessert Einige von uns erklären sie auch Und wir testen sie
      • Ziel des Vortrags
          In diesem Vortrag geht es um das
        • Erklären beim Schreiben von Anleitungen
        • Zeigen anhand von Beispielen
        • Prüfen der Beispiele in Tests
        • Aber eigentlich geht es darum, wie dies die Qualität von APIs verbessert.
      • Kosten eines schlechten APIs
        • Getrieben durch Anzahl Anwendungen
          • Auch in kleineren Teams relevant
        • Schlecht lesbarer Code
        • Fehler in der Anwendung
        • Nachdenken bei jedem Anwenden
        • oder Copy/Paste von Unverstandenem
        • Vertrauensverlust
        • Ein schlecht designtes zentrales API kann eine Code-Basis massiv schädigen!
      • Zitat
        • “ Good tests help you verify your code works , but good documentation forces you to question whether your code makes sense .” @sstephenson
      • Wie hilft das Erklären?
        • Fokus auf Anwender und ihre Bedürfnisse
          • Use Cases, User Stories
        • Erweitert die Perspektive
          • Zusammenspiel von Komponenten
          • Gesamtabläufe
        • Bremst Featuritis
          • Das muss nun auch noch alles erklärt werden
      • Erklären, die Zweite
        • Fördert Zusammenarbeit
          • Reviews der Usability des APIs
          • Vom Thron steigen
        • Macht ehrlich und überzeugend
          • Man muss für seine Arbeit einstehen
          • Speziell in Vorträgen!
      • Wie hilft das Zeigen?
        • Beispielcode erzählt Teil der Geschichte
        • Konsistente und überzeugende Begriffe
        • Prägnanter Anwender-Code
          • Vereinfachtes API für typische Fälle?
        • Kryptische Hacks stechen heraus
      • Was bringen Beispiele?
        • Korrekte und effiziente Verwendung
        • Gleichförmigen Anwender-Code
          • Einfacher zu lesen und zu warten
          • Kann Refactoring des APIs vereinfachen!
        • Feedback
          • Anwender fragen eher nach, wenn ihr Fall nicht abgedeckt ist, anstatt einfach zu wursteln.
      • Was hilft das Testen?
        • Vollständigkeit
          • Kein Händewedeln, keine Abkürzungen
        • Wartbarkeit
          • Beim Refactoring sieht man, wo Text betroffen ist.
        • Nachhaltigkeit
          • Führt beim Refactoring zurück zum Erklären und dem damit verbundenen Nachdenken!
        • Nutzen, der nicht dem API an sich dient:
          • Die Beispiele funktionieren. Immer.
          • Wichtiger Satz von automatisierten Tests
      • Aus der Praxis
        • Excel Compiler: http://formulacompiler.org/
        • Habe umfassende Tutorials geschrieben
          • Führte zu vereinfachten APIs für typische Fälle
          • Zwang zu Gründlichkeit bei komplexen Features
          • Lenkt Anwender zu bewährten Mustern
        • Habe in Vorträgen präsentiert
          • Zeigte Bedarf an weiterer Lenkung auf
      • Techniken
        • Code-First
          • Beispiele direkt als Test
          • Erklärung in Kommentaren im Test-Code
        • Prose-First
          • Erklärung direkt als Textdokument
          • Beispiele eingebettet oder aus Test-Code zitiert
      • Ein Experiment dazu
        • Dokumentierte Erweiterbarkeit von JCite: http://arrenbrecht.ch/jcite/
        • Zuerst mit Code-First fand ich
          • Schlechte Begriffe
          • Schlechte Abstraktionen, die zu Redundanz im Anwender-Code führten
        • Dann mit Prose-First fand ich
          • Noch mehr schlechte Begriffe
          • Sogar solche, die ich mit Code-First gerade eben eingeführt hatte!
      • Vorteile Code-First
        • Einfach und schnell eingerichtet
        • Gut von der IDE unterstützt
        • Anleitungen für Anwender direkt in IDE verfügbar
      • Vorteile Prose-First
        • Leeres Blatt führt zu tieferer Reflexion
        • Fokus auf User Story, Hintergrund und Zielen
        • Begriffe besser, wenn im Schreibfluss gewählt
        • Verknappte Beispiele ohne Ballast
        • Ergibt ausgestaltete Dokumentation
        • Fördert erneutes Durchlesen und Verbessern
      • Code-First
        • Beginne mit Tests, nicht mit dem API
        • Schreibe Einführungstext vor dem Test (leeres Blatt!)
        • Verberge Ballast
        • Trenne Beispieltests von technischen Tests
        • Verwende JavaDoc nicht für lange Anleitungen
          • Verweise stattdessen auf Beispieltests
        • Generiere evtl. Doku daraus: http://agical.com/bumblebee/
      • Prose-First
        • Beginne weit oben (Übersicht, Ziele)
        • Skizziere die Beispiele zunächst direkt im Text
          • So bleibt man auf die Story fokussiert
          • Beispiele danach in echte Tests überführen
        • Zitiere auch die Checks in den Tests
          • Prüft dieser Test wirklich was ich behaupte?
        • Zitiere so viel wie möglich
          • Kein Copy/Paste
        • Kehre wieder nach weit oben zurück
          • Sind die Ziele erreicht? Verweise zu Beispielen.
        • Checke mit dem Code zusammen ein
      • Caveat Emptor
        • Kurze Beispiele auf Kosten des APIs
          • Es gibt noch andere Kriterien für ein gutes API
          • Vorsicht beim Einführen von vereinfachten APIs
        • Anleitung ersetzt die Referenz nicht
        • Nicht alle Programmierer schreiben gut
          • Vorträge halten, Präsentationen im Haus
          • Reviews, Lektoren (aus Administration?)
          • Der Reflexion nicht ausweichen!
      • Den Kreis schliessen
          Was hat mich dieser Vortrag gelehrt?
        • Wie können wir externe Anleitungen in IDEs integrieren?
        • Wie die Zitate direkt im Dokumenteditor anzeigen?
        • Wenn ich Library-Code reviewe, dann bestehe ich auf Beispieltests.
      • Links
        • Twitter: @parrenbrecht
        • Literate Testing
          • http://arrenbrecht.ch/testing/
        • JCite
          • Zitiert Code-Ausschnitte in HTML-Dokumente
          • http://arrenbrecht.ch/jcite/
        • Bumblebee
          • Erzeugt HTML aus Kommentaren im Code
          • http://agical.com/bumblebee/bumblebee_doc.html
        • Vielen Dank!