Engineering Insights
Eine wichtige Fähigkeit für jeden Software-Ingenieur ist das Schreiben von Technical Design Docs (TDDs), auch Engineering Design Docs (EDDs) genannt. In diesem Artikel gebe ich einige Ratschläge für das Schreiben guter Entwurfsdokumente und zeige, welche Fehler zu vermeiden sind.
Ein Vorbehalt: Verschiedene Teams haben unterschiedliche Standards und Konventionen für den technischen Entwurf. Es gibt keinen branchenweiten Standard für den Entwurfsprozess, und es kann ihn auch nicht geben, da die verschiedenen Entwicklungsteams je nach Situation unterschiedliche Bedürfnisse haben werden. Was ich beschreiben werde, ist eine mögliche Antwort, die auf meinen eigenen Erfahrungen beruht.
Beginnen wir mit den Grundlagen: Was ist eine technische Entwurfsunterlage, und wie fügt sie sich in den Entwurfsprozess ein?
Eine technische Entwurfsunterlage beschreibt eine Lösung für ein bestimmtes technisches Problem. Es ist eine Spezifikation oder ein „Entwurfsplan“ für ein Softwareprogramm oder eine Funktion.
Die primäre Funktion eines TDD besteht darin, den Teammitgliedern die technischen Details der zu erledigenden Arbeit zu vermitteln. Es gibt jedoch noch einen zweiten Zweck, der ebenso wichtig ist: Der Prozess des Schreibens der TDD zwingt Sie dazu, Ihre Gedanken zu ordnen und jeden Aspekt des Entwurfs zu berücksichtigen, um sicherzustellen, dass Sie nichts ausgelassen haben.
Technische Entwurfsdokumente sind oft Teil eines größeren Prozesses, der typischerweise die folgenden Schritte umfasst:
- Produktanforderungen werden definiert. Diese werden in der Regel durch ein Produktanforderungsdokument (PRD) dargestellt. Das PRD gibt an, was das System aus der Sicht eines Benutzers oder eines externen Agenten leisten muss.
- Technische Anforderungen werden definiert. Die Produktanforderungen werden in technische Anforderungen übersetzt – was das System leisten muss, aber nun, wie es das tut. Das Ergebnis dieses Schrittes ist ein Technical Requirements Document (TRD).
- Technischer Entwurf. Dieser enthält eine technische Beschreibung der Lösung für die in den vorangegangenen Schritten skizzierten Anforderungen. Das TDD ist das Ergebnis dieses Schritts.
- Implementierung. Dies ist die Phase, in der die Lösung tatsächlich gebaut wird.
- Testen. Das System wird anhand des PRD und TRD getestet, um sicherzustellen, dass es die spezifizierten Anforderungen tatsächlich erfüllt.
Zwischen den einzelnen Phasen findet in der Regel ein Überprüfungsprozess statt, um sicherzustellen, dass keine Fehler gemacht wurden. Werden Fehler, Missverständnisse oder Unklarheiten festgestellt, müssen diese korrigiert werden, bevor mit dem nächsten Schritt fortgefahren wird.
Dieser Prozess ist sehr variabel; die hier aufgeführten Schritte werden sich von Fall zu Fall ändern. Zum Beispiel:
- Für kleinere Funktionen, die nicht sehr komplex sind, werden die Schritte 2 und 3 oft in einem einzigen Dokument zusammengefasst.
- Wenn die Funktion eine große Anzahl von Unbekannten oder ein gewisses Maß an Forschung beinhaltet, kann es notwendig sein, eine Proof-of-Concept-Implementierung zu erstellen, bevor der technische Entwurf abgeschlossen wird.
Dieser Prozess findet auch in verschiedenen Maßstäben und auf verschiedenen Ebenen der Granularität statt. Ein PRD / TRD / TDD kann den Entwurf eines ganzen Systems oder nur eines einzelnen Features betreffen. In den meisten Umgebungen ist der Prozess auch zyklisch – jeder Entwurfs-/Implementierungszyklus baut auf der Arbeit des vorhergehenden auf.
Die Grenze zwischen TRD und TDD kann manchmal etwas unscharf sein. Nehmen wir zum Beispiel an, Sie entwickeln einen Server, der über eine RESTful API kommuniziert. Wenn das Ziel darin besteht, einer bereits etablierten und dokumentierten API zu entsprechen, dann ist die API-Spezifikation Teil der Anforderungen und sollte im TRD referenziert werden. Wenn das Ziel hingegen darin besteht, eine völlig neue API zu entwickeln, dann ist die API-Spezifikation Teil des Entwurfs und sollte im TDD beschrieben werden. (Das Anforderungsdokument muss jedoch immer noch angeben, was die API erreichen soll.)
Das TDD schreiben
Heutzutage ist es üblich, technische Dokumente in einem kollaborativen Dokumentensystem wie Google Docs oder Confluence zu schreiben; dies ist jedoch keine absolute Voraussetzung. Wichtig ist, dass Ihre Teammitglieder die Möglichkeit haben, das Dokument zu kommentieren und auf Fehler und Auslassungen hinzuweisen.
Die meisten TDDs sind zwischen einer und zehn Seiten lang. Obwohl es keine Obergrenze für die Länge einer TDD gibt, sind sehr umfangreiche Dokumente sowohl schwierig zu bearbeiten als auch für die Leser schwer zu erfassen; erwägen Sie eine Aufteilung in separate Dokumente, die einzelne Schritte oder Phasen der Implementierung darstellen.
Diagramme sind hilfreich; es gibt eine Reihe von Online-Tools, mit denen Sie Illustrationen in das Dokument einbetten können, wie draw.io oder Lucidchart. Sie können auch Offline-Tools wie Inkscape verwenden, um SVG-Diagramme zu erzeugen.
Das Dokument sollte gründlich sein; idealerweise sollte es für jemanden anderen als den TDD-Autor möglich sein, das Design wie geschrieben zu implementieren. Wenn der Entwurf zum Beispiel die Implementierung einer API vorgibt, sollte jeder API-Endpunkt dokumentiert werden. Wenn es subtile Design-Entscheidungen gibt, sollten sie genannt werden.
Vermeiden Sie häufige Schreibfehler
Wahrscheinlich ist der häufigste Fehler, der mir in TDDs begegnet, ein Mangel an Kontext. Das heißt, der Autor hat in so wenigen Worten wie möglich aufgeschrieben, wie er das Problem gelöst hat, aber er hat keine Informationen darüber gegeben, was das Problem war, warum es gelöst werden musste oder welche Konsequenzen die Wahl dieser speziellen Lösung hatte.
Auch ist es wichtig, sich zu vergegenwärtigen, wer der wahrscheinliche Leser ist und welches Verständnisniveau er hat. Wenn Sie einen Begriff verwenden, den der Leser vielleicht nicht kennt, scheuen Sie sich nicht, eine Definition hinzuzufügen.
Es muss wohl kaum erwähnt werden, dass gute Grammatik und Rechtschreibung hilfreich sind. Vermeiden Sie auch die Versuchung von Wortspielen oder „niedlicher“ Rechtschreibung; obwohl Programmierer als Klasse dazu neigen, gerne mit der Sprache zu spielen, habe ich mehr als einen Fall gesehen, in dem übertriebene Frivolität das Team aufgrund von Missverständnissen am Ende unnötige Mühe gekostet hat. Es ist in Ordnung, gelegentlich Humor zu verwenden oder farbenfrohe, einprägsame Namen für Funktionen und Systeme zu wählen, denn das hilft den Leuten, sich an sie zu erinnern. Aber lassen Sie sich nicht davon ablenken, wie clever Sie sind.
Apropos Namen, wählen Sie sie sorgfältig aus; wie Mark Twain einmal schrieb: „Wählen Sie das richtige Wort, nicht seinen Cousin zweiten Grades.“ Ingenieure mit einem unzureichenden Wortschatz neigen dazu, dieselben allgemeinen Begriffe immer wieder für verschiedene Dinge zu verwenden, was zu Überlastung und Verwirrung führt. Eine Klasse „DataManager“ zu nennen, ist zum Beispiel vage und sagt nichts darüber aus, was sie eigentlich tut; ebenso könnte ein Paket oder Verzeichnis namens „utils“ praktisch alles enthalten. Konsultieren Sie einen Thesaurus, wenn Sie ein besseres Wort finden müssen, oder noch besser, eine spezialisierte Synonym-Datenbank wie WordNet.
TDD-Vorlage
Wenn Sie eine TDD schreiben, kann es hilfreich sein, mit einer Standardvorlage zu beginnen. Im Folgenden finden Sie eine Vorlage, die ich in einer Reihe von Projekten verwendet habe. Beachten Sie, dass diese Vorlage bei Bedarf angepasst werden sollte; es steht Ihnen frei, nicht zutreffende Abschnitte zu löschen, zusätzliche Abschnitte hinzuzufügen oder Überschriften nach Bedarf umzubenennen.