<ul><li>“Stimmige APIs kosten weniger.” Peter Arrenbrecht
codewise.ch @parrenbrecht </li></ul>Literate Testing
Wir alle designen APIs <ul></ul>Prüft Verbessert Einige von uns erklären sie auch Und wir testen sie
Ziel des Vortrags <ul>In diesem Vortrag geht es um das <li>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. </li></ul>
Kosten eines schlechten APIs <ul><li>Getrieben durch Anzahl Anwendungen </li><ul><li>Auch in kleineren Teams relevant </li...
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! </li></ul>
Zitat <ul><li>“ Good  tests  help you verify your  code works , but good  documentation  forces you to question whether yo...
Wie hilft das Erklären? <ul><li>Fokus auf Anwender und ihre Bedürfnisse </li><ul><li>Use Cases, User Stories </li></ul><li...
Gesamtabläufe </li></ul><li>Bremst Featuritis </li><ul><li>Das muss nun auch noch alles erklärt werden </li></ul></ul>
Erklären, die Zweite <ul><li>Fördert Zusammenarbeit </li><ul><li>Reviews der Usability des APIs
Vom Thron steigen </li></ul><li>Macht ehrlich und überzeugend </li><ul><li>Man muss für seine Arbeit einstehen
Speziell in Vorträgen! </li></ul></ul>
Wie hilft das Zeigen? <ul><li>Beispielcode erzählt Teil der Geschichte
Upcoming SlideShare
Loading in...5
×

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

375

Published on

Published in: Technology
0 Comments
0 Likes
Statistics
Notes
  • Be the first to comment

  • Be the first to like this

No Downloads
Views
Total Views
375
On Slideshare
0
From Embeds
0
Number of Embeds
0
Actions
Shares
0
Downloads
0
Comments
0
Likes
0
Embeds 0
No embeds

No notes for slide

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

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

×