Warum ich wegwerfbaren Code statt Designdokumente bevorzuge

• In der Softwareentwicklung führt ein Designdokument selten direkt zu einem sauberen PR; weil Annahmen erst beim tatsächlichen Coden ins Wanken geraten, kann es schneller sein, das Design mit wegwerfbarem Code zu erkunden
• Vorgeschlagen wird ein Ablauf, bei dem in einem nicht zum Mergen vorgesehenen Draft-PR ein Prototyp oder Proof of Concept entsteht, früh Review eingeholt wird, um die Richtung abzugleichen, und das Ganze anschließend als Aufzeichnung der Designidee erhalten bleibt
• Voraussetzung für diese Arbeitsweise ist die organisatorische Reife, die erste Lösung ohne Zögern verwerfen zu können; dieselbe Aufgabe auf 2–3 Arten zu implementieren, gilt als Signal von Seniorität
• PRs werden zu auffindbaren Dokumenten, die Implementierungsabsichten und Diskussionen eines bestimmten Zeitpunkts festhalten, während Designdokumente ohne häufige Aktualisierung leicht zu „undead documentation“ werden, die von der Realität abweicht
• Designdokumente bleiben weiterhin sinnvoll, wenn Feedback vieler Beteiligter gebündelt werden muss, ein langfristiges North-Star-Dokument gebraucht wird, Ideen noch zu früh zum Coden sind oder in einer Organisation das Risiko besteht, dass Prototypen unverändert ausgerollt werden

---

Das Design mit Throwaway-PRs erkunden

• Der ideale Entwicklungsablauf sieht so aus: ein Designdokument schreiben, kleine PRs nacheinander mergen, Features ausrollen und dabei eine saubere Git-Historie bewahren
• In der Praxis geraten die Annahmen im Designdokument oft erst ins Wanken, nachdem man mit dem Coden begonnen hat, und man muss neu entscheiden, in welcher Reihenfolge etwas veröffentlicht werden soll
• Deshalb kann es effizienter sein, zuerst ein größeres Code-Experiment zu bauen und auf Basis der Ergebnisse den eigentlichen Plan festzulegen

• Vorgeschlagener Ablauf

  • In einem Draft-PR ohne Merge-Absicht einen Prototyp oder Proof of Concept implementieren
  • Bei großen Refactorings oder beim Ansatz für ein Feature früh die Sicht anderer einholen, um Ausrichtung zu gewinnen
  • Den Ansatz im Draft-PR dokumentieren, damit ein historischer Nachweis der Designidee erhalten bleibt
  • Sich darauf vorbereiten, den gesamten Draft-PR so früh wie möglich zu verwerfen
  • Aus dem Draft-PR schrittweise tatsächlich ausrollbare PRs herausziehen und sie über etwa eine Woche in saubere Deployment-PRs aufteilen
  • Beim Aufteilen der PRs nach und nach Lücken bei Tests und Robustheit schließen

• Voraussetzungen im Team für diese Arbeitsweise

  • Die wichtigste Voraussetzung ist die Reife, die erste selbst geschriebene Idee verwerfen zu können
  • Sich wohl damit zu fühlen, dasselbe Problem auf 2–3 Arten zu coden, kann als wichtiges Signal von Seniorität gelten
  • Wert wird nicht durch die Zahl der in Produktion gegangenen Codezeilen geliefert, sondern durch das Wissen, das die Organisation gewonnen hat
  • Wenn man bei wichtigen Punkten früh Alignment erreicht, endet späteres Prototyping nicht einfach als Verschwendung
  • Man muss mit der Codebasis so vertraut sein, dass man ihre Kernbereiche schnell verbinden kann; von Senior-Mitarbeitenden darf man ein solches Maß an Sicherheit erwarten
  • Diese Arbeitsweise lässt sich nicht nur individuell, sondern auch als Team praktizieren

PR-Dokumentation und die tatsächliche Rolle von Designdokumenten

• PRs sind eine der nützlichen Dokumentationsformen für Entwickler
  • Sie sind oft einer der ersten Orte, an denen man nachschaut, wenn man verstehen will, warum eine bestimmte Implementierung so entstanden ist
  • Sie behaupten nicht, den aktuellen Stand abzubilden, sondern bleiben als historische Artefakte eines bestimmten Zeitpunkts erhalten
• Designdokumente werden leicht zu undead documentation, die eine veraltete Realität widerspiegelt, wenn sie nicht regelmäßig aktuell gehalten werden
• Prototypen passen zu „zeigen statt reden“, und beim Herbeiführen von Veränderungen kann Code wirksamer sein als Dokumentation
• In Organisationen ohne Disziplin besteht jedoch das Risiko, dass ein Prototyp nicht als „Frage“, sondern als „Antwort“ verstanden wird
  • Die ursprüngliche Absicht ist eher: „Sollen wir das tun, oder sollten wir etwas anderes tun?“
  • Wenn die Organisation es als „Das müssen wir tun“ auffasst, entsteht ein Problem

• Wann Designdokumente weiterhin passend sind

  • Sie sind nützlich, wenn Feedback von vielen Stakeholdern, Managern oder externen Teams gesammelt und aufbewahrt werden muss
  • Nur mit GitHub lässt sich eine solche Zusammenarbeit möglicherweise schwer abbilden
  • Wenn eine Idee zu konzeptionell und langfristig ist, um sofort in Code gegossen zu werden, kann ein gewisses North-Star-Dokument hilfreich sein
  • Sie sind nützlich, wenn sich etwas schriftlich effizienter ausdrücken lässt als als erster Code-Entwurf oder wenn man noch nicht tief genug in die Codebasis eingearbeitet ist und einen Entwurf für Feedback hinterlassen möchte
  • Wenn ein Unternehmen ohne die nötige Disziplin, die erste Lösung zu verwerfen, sofort auf Production-Rollout drängt, kann sich ein Prototyp unverändert als „Lösung“ verfestigen
  • In Organisationen, in denen Junior-Mitarbeitende einer Umsetzungsidee von Senior-Entwicklern nur schwer widersprechen können, kann ein weicheres Artefakt nötig sein, um sicherer Fragen zu stellen

• Wenn Designdokumente aus den falschen Gründen genutzt werden

  • In Teams mit zu wenig Disziplin oder Erfahrung können sie zu einem Mittel werden, Prozesse zu verlangsamen
  • Selbst wenn sie zur Dokumentation dienen, veralten sie in der Regel schnell
  • Es ist schwer, alle Designfragen im Voraus zu beantworten, und die eigentlichen Probleme zeigen sich oft erst nach dem Schreiben von Code
  • Wenn ein Team genügend Disziplin aufbringen kann, kann durch Hacken zu lernen effizienter sein als formales „Design“

[GN⁺]

Meinungen auf Hacker News

• Das nennt man Prototyping; es ist ein wertvoller Teil des Designprozesses, manche nennen es auch „Pathfinding“.
  All diese Dinge sind Eingaben für das Design, aber ein Design in angemessenem Umfang ist weiterhin nötig. Andernfalls baut man nur nach dem Prinzip „was gerade funktioniert“. Man muss definieren, welches Problem gelöst werden soll und wie die Lösung aussieht. Manchmal reicht ein einseitiges Dokument ohne formales Review, manchmal braucht es ein mehrseitiges Dokument mit wochenlangen Reviews und Feedback-Schleifen.
  Nicht vergessen: „Mit ein paar Wochen Coding kann man sich ein paar Stunden Planung sparen“ ;)

  • Design muss unbedingt verstanden werden, aber das bedeutet nicht zwingend ein Dokument oder ein dauerhaftes Artefakt. Wenn ein dauerhafter Nachweis nötig ist, kann auch ein PR ein völlig gutes Medium sein.
    Viel häufiger stimmte eher das Gegenteil. Leute planen und planen, bis der Plan nicht nur sinnlos wird, sondern die Produktivität aktiv beschädigt.
  • Es ist eher eine Frage von beidem statt entweder/oder. Man braucht Design und Prototyp.
    Ein paar Wochen Coding können ein paar Stunden Planung sparen, aber ein paar Wochen Planung können ebenfalls verschwendet sein. Auf Papier lässt sich leicht etwas schreiben, das unsinnig oder unmöglich ist. Zum Beispiel: „Eine Flotte von Einhörnern in einer halb traurigen Farbe anmalen“.
    Idealerweise sollten Design und Prototyp gemeinsam evolvieren und sich spiralförmig wie die Doppelhelix der DNA entwickeln, wobei die Iteration der einen Seite die nächste Iteration der anderen vorantreibt. Der große Vorteil, wenn man stärker zum Prototyping tendiert, ist: Nach einer Runde bleibt Software übrig, die tatsächlich etwas tut. Nach einer Designrunde bleibt praktisch nicht viel übrig.
  • Es gibt keinen Grund, nicht beides zu tun. Ich halte es für besser, zuerst die Theorie aufzuschreiben, dann mit einem Prototyp zu zeigen, ob sie funktioniert oder nicht, und danach das eigentliche Designdokument zu schreiben.
    Und auch bis in die Implementierungsphase hinein sollte man weiter priorisieren, dass Code wegwerfbar bleibt. Je leichter er zu löschen ist, desto besser.
  • Genau: Prototyping und Pathfinding sind völlig in Ordnung und meistens nötig.
    Aber Software Engineering ohne Designdokument oder irgendeine Art von Spezifikation, sei sie noch so knapp, ist kein Engineering, sondern eher das Bauen einer Baumhütte.
    Je größer und wichtiger ein Projekt wird, desto schneller treten Probleme und technische Schulden zutage.
  • „Mit ein paar Wochen Planung kann man sich auch ein paar Stunden Coding sparen“ :)

• Schreiben ist wirklich nützlich, um den Problemraum zu erkunden.
  Oft dachte ich, ich hätte ein Problem sicher verstanden, doch sobald ich anfing, es aufzuschreiben, tauchten neue und wichtige Fragen auf. Solche Dinge sieht man meist besser aus einer abstrakten Perspektive, oder sie zeigen sich in den ersten paar Release-Meilensteinen vielleicht noch nicht.
  Ich muss an einen Mentor aus meiner frühen Karriere denken. Er hatte nachträglich eine Active/Active-Konfiguration für ein Payment Gateway entworfen, öffnete Lucidchart und sagte: „Dieses Diagramm steht für sechs Monate meines Lebens.“
  Es ist nicht immer nötig oder hilfreich, aber wenn es nötig ist, können ein paar Tage Planung Wochen an Coding sparen.

  • Ich hatte einen Chef mit Mathematikabschluss, der wie Mathematiker im Fernsehen oder im Film den Ablauf von Anfang bis Ende auf dem Whiteboard skizzierte.
    Er konnte Stellen, an denen Probleme auftreten würden, viel früher vorhersagen, sodass Projekte immer reibungslos liefen. Wenn ein Problem oder eine Unsicherheit sichtbar wurde, modellierte er nur diesen Teil und kehrte dann zum Whiteboard zurück, um weiterzumachen.
    Als Analogie: Es ist wie die Planung einer Autofahrt mit einer Karte. Heutige Designdokumente markieren nur die Route und fahren dann sofort los, während die Whiteboard-Karte dieses Chefs „übermäßig geplant“ war: wo man tankt, Öffnungszeiten von Sehenswürdigkeiten, Dokumente für Grenzübertritte, Gesamtbudget, Notfallset, Plan A und Plan B.
    Extrem langweilig, aber deutlich besser als Wegwerf-Code. Inzwischen fühlt es sich für mich faul an, nicht übermäßig zu planen.
    Natürlich stimmt der Spruch „Jeder hat einen Plan, bis er eine verpasst bekommt“, aber das gilt für Krieg, Politik und Verhandlungen, nicht fürs Coding.
  • Ich stimme zu, dass Schreiben nützlich ist. Aber ich glaube, dass Coding denselben Effekt haben kann. Meiner Erfahrung nach müssen bei der Erkundung beide zusammengehen.
    Am Ende steckt auch in einem guten PR viel Text, und er hat denselben Effekt. Ein gut dokumentierter Draft-PR ist meiner Ansicht nach besser als ein reiner Designvorschlag. Denn wenn man nur schreibt, vergisst man wichtige Einschränkungen, die einem nur einfallen, wenn man im Code steckt.
  • „Schreiben ist die Art der Natur, dir zu zeigen, wie schlampig dein Denken ist.“
    -- Dick Guindon

• Das größte Problem, das ich mit Designdokumenten hatte, ist, dass niemand sie liest. Selbst dann nicht, wenn der Arbeitgeber sie verlangt.
  Das größte Problem, das ich mit Prototyping hatte, ist, dass Leute es als „Release-Code“ betrachten und einen zwingen, ihn als endgültigen Code zu verwenden.
  Deshalb hat ein gemischter Ansatz für mich am besten funktioniert: viel Zeit in Planung und Dokumentation investieren, aber im Grunde für mich selbst, und Prototyp-Code in Release-Qualität schreiben, damit er später auch im Endprodukt verwendet werden kann.

  • Der Grund, warum Menschen durchschnittliche Designdokumente nicht lesen wollen, ist, dass der durchschnittliche Software Engineer nicht die nötigen Schreibfähigkeiten besitzt, um Konzepte klar und prägnant auszudrücken.
    Designdokumente werden zu Bündeln roher Notizen, die niemand außer dem Autor wirklich versteht, und Menschen fürchten sich davor, solche Notizen zu lesen.
    Wenn man den Autoren von Designdokumenten aber erklärt, dass das hier wie eine benotete Abschlussarbeit in der Schule ist, kann der Text durch ein paar Überarbeitungen ziemlich gut werden. Das Symptom ist dasselbe wie beim Prototyping. Leute schreiben Designdokumente in Entwurfsqualität und erwarten, dass sie sich magisch in gute Texte für ein breiteres Publikum verwandeln. So wie Prototyp-Code ein paar Refactorings braucht, brauchen auch Designdokumente mehrere Überarbeitungen.

• Um eine Vertragsverlängerung zu vermeiden, mussten wir bis zur Deadline etwas bauen und releasen, und dieser Vertrag hätte mehrere Millionen Dollar gekostet. Dann wurde klar, dass wir es mit den geplanten Ressourcen und dem geplanten Ansatz nicht rechtzeitig schaffen würden.
  Also bekam ich die Freigabe, schnell eine provisorische, teilweise und nicht optimale Version zu bauen, und dadurch konnten wir rechtzeitig abheben.
  Damit konnten wir eine Weile fliegen, während andere die dauerhafte, ordentliche Version dieses Teils des Flügels fertigstellten.
  Tatsächlich entdeckten wir während des Flugs auch Anforderungen, die im ursprünglichen Design fehlten. Das verzögerte zwar den Produktions-Release der ordentlichen Version, aber in meine Hack-Version konnte ich sie schnell einbauen und den Betrieb weiter aufrechterhalten.
  Meine Hack-Version dient auch als Production-Support-Tool. Wenn die dauerhafte Version wegen eines Bugs angehalten werden muss, ist sie auch ein Ausweichpfad. Sie ist ein partieller, unvollständiger Hack, hat aber ihre Vorteile.
  Manche beschwerten sich darüber, dass die verwendete Sprache weniger verbreitet war. Man muss sich aber daran erinnern, dass wir mit den vorhandenen Ressourcen und dem vorhandenen Ansatz überhaupt nicht abgehoben wären.
  Um die Deadline zu schaffen, hätten wir mehr oder schnellere Entwickler in der bevorzugten Sprache gebraucht. Wenn jemand aus der aktuellen Belegschaft, mich eingeschlossen, in der bevorzugten Sprache die freie Kapazität und Fähigkeit gehabt hätte, so produktiv zu sein wie ich mit meinem Nischensprachen-Hack, wäre diese Person damit beauftragt worden, die dauerhafte Lösung rechtzeitig zu bauen. Diese Option gab es nicht.
  Jedenfalls: Wenn es ein bestehendes Production-Support-Tool gibt, ist das auch ein Ort, an dem Prototyp-Funktionen eine Weile bleiben können.

  • Welche Sprache war das?

• Wieder ein Meinungsbeitrag, aber ohne Daten und nicht einmal mit konkreten Beispielen.
  Ich weiß, dass alle Software Engineers starke Meinungen haben, aber das ist ein schwaches Argument. Wenn man glaubt, dass der Job darin besteht, viel Code zu schreiben, um zu sehen, was richtig ist, wird man bald von GPT ersetzt werden. Das kann es schneller und billiger. Der schwierige Teil besteht immer darin, Einigkeit darüber herzustellen, was gebaut werden soll, und durch Coding kommt man aus diesem Problem nicht heraus.

  • Stimme stark zu. Ob „Designdokument“ der richtige Begriff ist, weiß ich nicht; ich nenne es technische Analyse. Aber Dokumente zu schreiben, die Business- und Produktanforderungen mit Implementierungsdetails verbinden, ist äußerst nützlich, damit alle dasselbe Verständnis von Anforderungen und Ergebnissen haben.
    Wenn die Anforderungen klar sind und allen klar ist, was ich liefern werde, braucht man das nicht. Dann kann man direkt ins Prototyping gehen. Bei ernsthaften Projekten ist das aber selten der Fall. Es gibt immer unbekannte Unbekannte, die man den Stakeholdern entlocken muss, und technische Analyse ist eine gute Methode dafür.
  • Genau das ist mein Punkt. Ich glaube, „zeigen statt erzählen“ führt zu besserer Einigung.
    Rechtecke und gestrichelte Linien haben ihre Grenzen. Wenn man vom echten Code entfernt ist, vergisst man die echten Einschränkungen. Die Dinge, die einen tatsächlich bremsen, tauchen in Google Docs nicht auf. Nach meiner Erfahrung kommt man weiter, wenn man sagt: „Das ist, was ich mir vorstelle“, und auf einen Draft-PR zeigt.
    Und ja, das ist zu 100 % Meinung. Es ist ein persönlicher Blog, kein peer-reviewtes Paper :) Es ist okay, falsch zu liegen.
  • Wegwerfcode ist besser als ein Designdokument, weil er ein konkretes Beispiel ist.
    Ohne etwas Greifbares wie Code, an dem sich die Diskussion festhalten kann, laufen Gespräche über abstrakte Designs zwangsläufig in ergebnislose Debatten nach dem Muster „Meine imaginäre Schnur ist länger als deine imaginäre Schnur“.
  • Es ist wahrscheinlicher, dass Menschen mit dieser Überzeugung sich mit LLMs deutlich schneller bewegen, als dass LLMs diese Arbeit komplett ersetzen.
  • Die „Daten“ solcher Texte können manchmal Jahrzehnte persönlicher Erfahrung sein.

• Nach meiner Erfahrung ist Feedback zu Code und Feedback zu Design von enorm unterschiedlicher Art.
  Designdokumente provozieren „Warum“-Fragen, die alle dazu bringen, über den Problemraum nachzudenken. Zum Beispiel ist ein Kommentar möglich wie: „Warum schlagen Sie einen Rust-Webserver vor, obwohl im Unternehmen noch niemand gut mit Rust umgehen kann?“
  Solche subtilen Fragen sind viel schwerer zu stellen, sobald ein Prototyp zu funktionieren beginnt. Schnell heißt es dann: „Warum ist die Erfahrung des Teams wichtig? Es läuft doch so gut! Wenn Sie uns nur nicht blockieren, können wir den Prototyp einfach etwas aufpolieren und innerhalb einer Woche in Production bringen!“

  • Das ist nicht unbedingt schlecht. Viele „Warum“-Fragen sind wirklich unproduktive Bikeshedding-Debatten.
    Besonders dann, wenn man nur ein Design prüft und keinen funktionierenden Code.

• Wir stellen uns vor, dass Softwarearbeit einem sauberen, geordneten Ablauf folgt.
  Man schreibt ein Designdokument, erstellt in PRs kleine inkrementelle Änderungen, um ein Feature zu releasen, und die Git-Historie ist sauber und ordentlich. Es sieht nach stetigem Fortschritt aus.
  Wer stellt sich das so vor? Professoren, die Software-Engineering-Kurse unterrichten?
  Das erinnert mich an Leute, die glauben, Prosa, Essays, Geschichten, Romane usw. würden geschrieben, indem man erst eine Gliederung erstellt und diese dann mit Prosa „auffüllt“ – als gäbe es in diesem Prozess keinerlei Entdeckungen, die ein Umschreiben oder Umstrukturieren des Dokuments nötig machen. Niemand schreibt so. Entwürfe sind immer schlecht, und fast jeder gute Text ist das Ergebnis umfangreicher Überarbeitung.
  Code zu schreiben ist dem Schreiben viel näher als dem Bau eines Hauses oder einer Brücke.

  • Ich sehe immer großen Wert darin, neu geschriebenen Code zu debuggen.
    Die neue Logik Zeile für Zeile durchzugehen und Variablen und Speicher anzusehen, hilft wirklich dabei, den Code zu verbessern. Man entdeckt Dinge wie: „Ah, diese lokale Variable brauche ich nicht“, „Hier sollte ich eine temporäre Variable hinzufügen, damit es leichter zu debuggen ist“, oder „Dieser Code verhält sich komisch, wenn die Collection, über die ich iteriere, leer ist.“
    Egal wie alt man wird oder wie viel Code man schreibt: Beim Debuggen von frisch geschriebenem Code entdeckt man immer etwas Neues. Das lässt sich vielleicht damit vergleichen, dass ein Autor nach dem Schreiben eines Entwurfs noch einmal liest oder ihn sich selbst oder anderen laut vorliest.

• Ich mag diesen Prozess sehr, Designentscheidungen nicht in einem einzelnen Dokument zu formalisieren, sondern in einem laufenden Kommentar-Thread festzuhalten.
  Ich verwende GitHub-Issues so, funktional ist es aber dasselbe wie ein PR. Ein PR ist im Grunde ein GitHub-Issue mit angehängtem Code-Branch.
  Mehr zu meiner Vorgehensweise habe ich hier geschrieben: https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/...

  • Wie vermittelst du dann den aktuellen Konsens zu allen Issues? Zum Beispiel neuen Leuten, die nicht durch Monate an Kommunikation scrollen wollen, oder Teammitgliedern, die zwar die ganze Zeit im Thread dabei waren, aber nicht leicht finden, worauf sich das Team bei einem bestimmten Punkt geeinigt hat?
    Anders gesagt: Wie fasst du diesen Thread als endgültiges Dokument zusammen?

• Ich glaube nicht, dass sich beides gegenseitig ausschließt
  Design-Dokumente sind ein weiter gefasstes Konzept, und das Ziel ist Kommunikation
  Manchmal muss man etwas auf andere Weise als durch Code vermitteln. Diagramme, Bilder, Texte usw. sind nötig

  • Stimme zu
    Für jemanden, der nicht der Autor ist oder mit dem Code nicht sehr vertraut ist, ist es äußerst schwierig, Änderungen auf einen Blick zu verstehen. Damit Leser schnell das richtige mentale Modell aufbauen können, um eine Änderung im Kontext zu verstehen, braucht es Erklärungen und Dokumentation auf einer höheren Ebene
    Wenn du dir einen Diff mit 1000 Zeilen ansehen und genau sagen kannst, was er tut – und noch wichtiger, welche Auswirkungen er upstream und downstream hat –, dann lügst du entweder, oder du arbeitest in einer so perfekt abgeschotteten und überprüfbaren Umgebung, dass ich dich wirklich darum beneide

• Design-Dokumente helfen dabei, die Zahl der Prototypen unter den möglichen Optionen auf 2 bis 3 zu reduzieren. Das ist besonders nützlich, wenn man erkundet, wie man etwas völlig Neues hinzufügt
  Ich finde zwar, dass Zeigen besser ist als Erklären, aber neu Hinzugekommene verstehen es über ein Design-Dokument leichter als über Code