• 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

  • 525 views

 

Statistics

Views

Total Views
525
Views on SlideShare
525
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!