Das Geheimnis besserer APIs. Sie nutzen es nicht.

Haben Sie schon einmal ein Projekt voller Begeisterung begonnen, nur um sich dann in einem Netz aus verwirrendem Code und unklaren APIs zu verfangen? Damit sind Sie nicht allein.

Was wäre, wenn ich Ihnen sage, dass es eine geheime Methode gibt, die Top-Entwickler nutzen, um bessere APIs und reibungslosere Projekte zu erstellen – eine Methode, die Sie wahrscheinlich nicht anwenden?

Heute werde ich Ihnen eine wenig bekannte Technik für besseres API-Design vorstellen: README-Driven Development (RDD).

Was ist README-Driven Development (RDD)?

Was genau ist RDD?

Ganz einfach: Sie schreiben ein README, bevor Sie Code schreiben.

In diesem README beschreiben Sie die API Ihres Codes. Sie schreiben es so, als ob der Code, die REST-API, das Paket, das Framework – was auch immer Sie entwickeln – bereits existiert.

Anschließend teilen Sie Ihr README mit Ihren Kollegen für berufsbezogene Projekte oder mit Freunden für Nebenprojekte, damit diese Feedback geben können. Sie verbessern das README basierend auf deren Input. Wiederholen Sie diesen Prozess, bis alle mit der API zufrieden sind und alle möglichen Grenzfälle berücksichtigt wurden.

RDD geht oft Hand in Hand mit Test-Driven Development (TDD). Sie erfassen Ihre API in Ihren Tests und schreiben dann den Code, damit diese Tests bestehen.

So funktioniert's:

1. Schreiben Sie die API in das README, als ob sie bereits existiert.
2. Holen Sie Feedback von Ihren Kollegen ein und setzen Sie es um.
3. Erfassen Sie die API, indem Sie Tests schreiben.
4. Schreiben Sie den Code, damit die Tests bestehen.

Warum RDD?

RDD bietet zahlreiche Vorteile:

• Design-First-Ansatz: Es zwingt Sie dazu, zuerst über die Eingaben und Ausgaben nachzudenken. Indem Sie sich von Anfang an auf die API konzentrieren, verhindern Sie, dass Implementierungsdetails in Ihr API-Design gelangen.
• Frühe Feedback-Schleife: Das frühzeitige Ausformulieren der API ermöglicht es Ihren Kollegen, diese zu kritisieren und technische Design-Implikationen zu diskutieren. Ziel ist es, eine API zu entwickeln, die die beste Entwicklererfahrung bietet.
• Zweckklarheit: RDD hilft, den Zweck und Umfang des Projekts von Anfang an zu definieren. Diese Klarheit reduziert Fehler, die durch ein Missverständnis der zu entwickelnden Funktion entstehen. Sie kann auch Scope Creep verhindern und das Projekt auf seine beabsichtigten Ziele konzentrieren.
• Vermeidung redundanter Arbeit: Indem Sie die API frühzeitig festlegen, können Sie die redundante Arbeit vermeiden, Code später neu schreiben zu müssen, um die API zu ändern, wenn Änderungen kostspieliger und komplexer sein können. Wenn Sie alle Randfälle frühzeitig berücksichtigen, können Sie unnötige Nacharbeiten vermeiden.
• Bessere Dokumentation: Indem Sie sich zuerst auf die README konzentrieren, stellen Sie sicher, dass die Dokumentation KEIN nachträglicher Gedanke, sondern ein Kernbestandteil des Entwicklungsprozesses ist. Dies führt zu einer besseren, umfassenderen Dokumentation, die Benutzern und Wartenden zugutekommt.
• Effizientes Onboarding: Eine gut dokumentierte Codebasis mit einer klaren README erleichtert neuen Teammitgliedern das schnelle Verständnis des Projekts, wodurch die Einarbeitungszeit erheblich verkürzt wird.
• Ermöglicht Parallelisierung: Wenn Sie die Dokumentation zuerst schreiben, können Teams parallel arbeiten, weil jeder weiß, was er voneinander erwarten kann.

Mit anderen Worten, RDD stimmt eng mit einem grundlegenden Prinzip der Softwareentwicklung überein:

„Programmiere gegen ein Interface, nicht gegen eine Implementierung.“ – Gang of Four

Was sollte in der README enthalten sein?

Fügen Sie alles ein, was eine normale README enthalten würde:

• Funktionen: Listen Sie die Funktionen Ihres Projekts auf. Halten Sie fest, warum Sie es erstellen und welche Probleme Sie lösen. Dies hilft Benutzern – und Ihnen selbst –, zu verstehen, was das Projekt leisten soll. Basierend auf diesen Funktionen können Sie Ihre API planen.
• Installationsanweisungen: Geben Sie an, wie Ihr Paket oder Ihre Bibliothek installiert wird. Wenn Ihr Modul von anderen Paketen abhängt, listen Sie die Abhängigkeiten auf.
• Anwendungsbeispiele: Zeigen Sie, wie Sie Ihr Paket oder Ihre Bibliothek verwenden und welche Konfigurationsoptionen verfügbar sind.
• API-Dokumentation: Dokumentieren Sie die API Ihres Pakets oder Ihrer Bibliothek. Stellen Sie sicher, dass Sie gängige Anwendungsfälle abdecken. Dies ähnelt den Anwendungsbeispielen, hilft Ihnen aber, die API aus verschiedenen Perspektiven zu betrachten, z. B. aus der Sicht des Benutzers und des Entwicklers.
• Mitwirken: Erklären Sie, wie man zu Ihrem Paket oder Ihrer Bibliothek beitragen kann. Wenn Sie in einem internen Entwicklungsteam arbeiten, können Sie bestehende Entwicklungsprozesse festhalten oder hinterfragen.
• Lizenz: Fügen Sie die Lizenz Ihres Pakets oder Ihrer Bibliothek hinzu.

RDD-Beispiel

Schauen wir uns ein Beispiel an.

Angenommen, Sie möchten ein einfaches Paket erstellen, mit dem Sie Zufallszahlen generieren können.

Schritt 1: Das README schreiben

Zuerst halten Sie fest, was Ihr Projekt leisten soll und welche Probleme seine Funktionen lösen.

Zufallszahlengenerator

Generieren Sie Zufallszahlen mühelos.

Funktionen

• Generieren Sie Zufallszahlen zwischen beliebigen zwei Zahlen.
• Keine externen Abhängigkeiten.

Sobald Sie herausgefunden haben, was Sie tun möchten, möchten Sie Ihren Benutzern zeigen, wie sie anfangen und Ihr Projekt nutzen können. Fügen Sie also die fehlenden Abschnitte wie Installationsanweisungen, Anwendungsbeispiele, API-Dokumentation, Mitwirken und Lizenz hinzu.

Installation

npm install random-integer-generator

Verwendung

import generateRandomInteger from "random-integer-generator";

const randomNumber = generateRandomInteger(10, 50);
console.log(randomNumber); // Outputs a number between 10 and 50

API

generateRandomInteger(options)

• min (Zahl): Der Mindestwert (einschließlich).
• max (Zahl): Der Höchstwert (einschließlich).
• Rückgabe: Eine zufällige Ganzzahl zwischen min und max.

Mitwirken

Beiträge sind willkommen! Bitte eröffnen Sie ein Issue oder reichen Sie einen Pull Request ein.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.

Schritt 2: Feedback einholen

Nehmen wir an, Sie zeigen Ihr README Ihren Kollegen, damit diese es begutachten können. Ihre Kollegen weisen auf einige Möglichkeiten hin, den Zufallszahlengenerator zu verbessern:

• Die Funktion generateRandomInteger sollte ohne Argumente aufrufbar sein.
• Sie sollte einen Standardbereich von 0 bis 100 haben.
• Sie sollte benannte Parameter über ein Options-Objekt entgegennehmen.
• Zuletzt sollte sie ein benannter Export sein, damit Sie zukünftig problemlos weitere Funktionen hinzufügen können.

Sie einigen sich mit Ihren Kollegen und aktualisieren die README-Datei.

Schritt 3: Tests schreiben

Nun ist es Zeit, Ihr Projekt zu erstellen, damit Sie Code schreiben können.

mkdir random-integer-generator
cd random-integer-generator
npm init -y

Installieren Sie dann Ihre bevorzugte Testbibliothek. In diesem Fall verwenden wir Vitest.

npm install vitest --save-dev

Schritt 4: Den Code schreiben, damit die Tests bestehen

Implementieren Sie schließlich den Code, der die README-Anforderungen erfüllt und die Tests besteht.

export const randomInteger = ({ min = 0, max = 100 } = {}) =>
  Math.floor(Math.random() * (max - min + 1)) + min;

Wann RDD verwenden?

RDD kann in diesen Szenarien hilfreich sein:

1. Wenn es eine komplexe API gibt, die korrekt umgesetzt werden muss und die typischerweise von vielen Stakeholdern genutzt wird.
   • Open-Source-Projekte: Wenn Sie in einem Team arbeiten und etwas als Open Source anbieten möchten. Zum Beispiel ein SDK, das sich mit dem von Ihnen entwickelten Dienst verbindet.
   • Interne Bibliotheken: Wenn Sie ein internes Tool entwickeln, das von mehreren Teams in Ihrem Unternehmen genutzt wird.
   • Komplexe Subsysteme: Wenn Sie an einer App oder einem Dienst arbeiten, bei dem mehrere Komponenten interagieren.
2. Wenn große, funktionsübergreifende Teams parallel arbeiten müssen und Sie sicherstellen möchten, dass ein Team nicht durch ein anderes blockiert wird.

Kompromisse

Ja, das Schreiben der README-Datei und das Einholen von Feedback von Kollegen kann den Prozess anfänglich langsamer machen als die reguläre Entwicklung. Unter den richtigen Umständen bietet RDD jedoch einen hohen Return on Investment.

Wenn Sie alleine arbeiten, kann RDD wenig Mehrwert bieten, wenn Sie bereits TDD verwenden.

Vorsicht vor Umfangserweiterung

Sobald Sie Ihr README für Ihre Traum-API haben, konzentrieren Sie sich auf die Kernfunktionalität für Version 1 und planen Sie, zusätzliche Funktionen in zukünftigen Versionen hinzuzufügen.

Warum Sie RDD nicht nutzen

Viele Entwickler überspringen RDD, weil:

• Sie haben noch nie davon gehört: Es wird weniger breit diskutiert als andere Methoden.
• Programmier-Eifer: Die Begeisterung für das Programmieren kann die Planung in den Schatten stellen.

Da Sie nun das Geheimnis kennen, wissen Sie, wann und wie Sie RDD einsetzen können, um bessere APIs zu entwickeln und erfolgreichere Projekte voranzutreiben. Bevor Sie Ihr nächstes Projekt starten, eine neue Funktion einführen oder eine neue Bibliothek erstellen, nehmen Sie sich einen Moment Zeit, um zuerst das README zu schreiben. Es mag sich anfangs etwas ungewöhnlich anfühlen, aber die Vorteile sind beträchtlich.