Sparen Sie sich den Kopfzerbrechen und dokumentieren Sie Vereinbarungen richtig

Vereinbarungen sind ein wesentlicher Bestandteil der Softwareentwicklung. Sie senken die Entwicklungskosten und machen das Leben der Entwickler einfacher. Aber es gibt ein Problem: Sie verkomplizieren die Dinge oft, weil sie nicht ordnungsgemäß dokumentiert und im Team nicht mündlich weitergegeben werden, wie alte Märchen. Während der Ausbreitung ändern sich Vereinbarungen. Plötzlich tauchen neue Details auf und alte sind verschwunden. Am Ende hat jedes Teammitglied sein eigenes Einverständnisbild im Kopf, und selbst dieses Bild verschwindet manchmal.

Schlimmer noch: Wenn Teams mit der Dokumentation dieser Vereinbarungen beginnen, tun sie dies willkürlich und erzeugen oft ein Durcheinander lose verknüpfter Dokumente, von denen die Hälfte nicht einmal aktuell ist.

In diesem Artikel verrate ich Ihnen , wie Sie Vereinbarungen richtig dokumentieren, damit diese Ihnen weiterhelfen.

Wie können wir also Vereinbarungen hilfreich gestalten? Wir müssen sie nicht nur dokumentieren, sondern auch tun, damit:

• sie waren einfach zu bedienen;
• Die Einhaltung dieser Vereinbarungen erforderte nur minimalen Aufwand.
• es wäre leicht zu verstehen, ob diese Vereinbarungen noch gültig wären;
• es wäre leicht zu verstehen, warum diese Vereinbarungen überhaupt existieren;
• Im Idealfall waren sie automatisiert.

  
  

Es gibt viele Möglichkeiten, Vereinbarungen zu klassifizieren. Ich werde sie nach ihrem Abstraktionsniveau aufteilen:

• Vereinbarungen auf Codeebene;
• Vereinbarungen auf Architekturebene;
• Vereinbarungen auf Prozessebene.

Vereinbarungen auf verschiedenen Ebenen erfordern unterschiedliche Arten ihrer Dokumentation und bringen unterschiedliche Vorteile mit sich. Werfen wir einen Blick auf jedes Level.

Konventionen auf Codeebene

Ziel dieser Vereinbarungen ist es, den Code einheitlich, umfassend und lesbar zu machen. Hier sind einige Beispiele:

• Wir verwenden doppelte Anführungszeichen anstelle von einfachen.

• Wir rufen ENV nicht direkt aus dem Code auf, außer in der Config -Klasse, wo wir diese Aufrufe in Methoden einbinden.

• Serviceobjekte haben das Postfix Service und einen öffentlichen call .

  
  

Diese Art von Vereinbarungen werden erstellt, um die kognitive Belastung des Lesers zu verringern und ihm zu helfen, sich schneller an unbekannten Code zu gewöhnen. Wie Martin sagte, wird Code bis zu zehnmal häufiger gelesen als geschrieben.

Trotz Ihrer Meinung zum Ruby on Rails-Framework verfügt es im Kern über ein unglaubliches convention over configuration , das es jedem Rails-Entwickler ermöglicht, das Projekt eines anderen zu öffnen und sich sofort ziemlich gut darin zurechtzufinden.

Wie kann man diese Konventionen dokumentieren? Linter-Werkzeug! Wenn es keine passende Linter-Regel gibt, schreiben Sie Ihre eigene Lint. Fast jeder Linter ermöglicht Ihnen dies: Hier ist ein Beispiel in und hier ein Beispiel für .

Die Verwendung von Linter für solche Kongresse bietet Ihnen drei Vorteile:

• Ein Entwickler muss nicht darüber nachdenken – Linter wird jeden Fehler hervorheben und ihn oft sogar für Sie beheben.
• Wenn Sie in Ihrem Team Codeüberprüfungen einsetzen, entlasten Sie Ihre Prüfer davon, über diese Dinge nachzudenken, und geben ihnen mehr Zeit, sich mit wichtigeren Dingen zu befassen.
• Der Entwickler wird ein Problem gleich zu Beginn des Entwicklungszyklus erkennen und es daher sofort beheben, ohne später Zeit für die Rückkehr zum Kontext aufzuwenden. Es wird günstiger, die Vereinbarung einzuhalten.

  
  

Ein weiterer Bonus: Das Schreiben einer neuen Linter-Regel ist eine hervorragende Schulung für einen Nachwuchsentwickler. Während er diese Aufgabe erledigt, wird er viel über das Parsen von Code und den Aufbau von AST lernen und die Sprache besser verstehen.

Konventionen auf Architekturebene

Hierbei handelt es sich um eine Vereinbarung auf höherer Ebene, die darauf abzielt, Ihre Architektur durchdacht, kohärent und einheitlich zu gestalten. Ein paar Beispiele:

• Wir verwenden Python, um reguläre Dienste und Elixir in den hochbelasteten Teilen des Systems zu schreiben.
• Das Backend gibt Fehler im beschriebenen Format zurück.

• Jeder Dienst ist zum Senden von Metriken in prometheus erforderlich. Auf dem Endpunkt /metrics wird der Port zum Senden von Metriken durch die Umgebungsvariable PROMETHEUS_PORT konfiguriert.

  
  

Solche Vereinbarungen reduzieren nicht nur die kognitive Belastung, sondern lösen auch drei weitere Probleme:

1. Reduzieren Sie die Betriebskosten. Wenn die Dienste auf die gleiche Weise, mit demselben Protokollformat und der Veröffentlichung derselben Metriken gestartet werden, ist es viel einfacher, den Dienst zu warten und mit Vorfällen umzugehen.
2. Reduzieren Sie die Designkosten. Der Entwickler muss die Architektur nicht jedes Mal von Grund auf neu entwerfen – das haben Sie im Voraus gedacht, und jetzt muss er nur eine bestimmte Funktion oder einen bestimmten Dienst entwerfen, ohne sich um grundlegende Dinge zu kümmern.
3. Reduzieren Sie die Kommunikationskosten. Wenn das Antwort- oder Ereignisformat des Servers in Kafka vorbestimmt ist, müssen Entwickler ihre Interaktion nicht jedes Mal besprechen, sondern können sich einfach auf die Konvention beziehen.

   
   

Solche Vereinbarungen sind komplexer und ich bevorzuge es, sie in zwei Schritten festzulegen.

Schritt 1 – Beschreiben

Architecture Decision Record (ADR) ist ein Tool zur Dokumentation solcher Vereinbarungen. Der Reiz besteht darin, dass es Metainformationen zusammen mit einer Vereinbarung erfasst: Warum wurde eine solche Vereinbarung angenommen? welche Alternativen wurden diskutiert; wann es zuletzt überarbeitet wurde; Ist die Vereinbarung noch gültig?

Dies ermöglicht es dem neuen Teammitglied, die Gründe für die getroffenen Entscheidungen zu verstehen und nicht die Leute in der Umgebung danach zu fragen.

ADR besteht aus mehreren Hauptblöcken:

1. Welches Problem löst die Vereinbarung?
2. Welche Möglichkeiten zur Lösung des Problems wurden in Betracht gezogen und welche Vor- und Nachteile hatten sie?
3. Welche Option wurde am Ende gewählt?

   
   

Es kann zusätzliche Blöcke geben – zum Beispiel die Berechnung der Implementierungskosten.

Es ist bequemer, ADR in einem System aufzubewahren, in dem man den Verlauf der Änderungen und Diskussionen einsehen kann. Meine Wahl fällt auf Github und Notion, beide haben ihre Vor- und Nachteile. Der Vorteil von Github besteht darin, dass es sofort über ein Überprüfungstool und einen Versionsverlauf verfügt. Notion kann aufgrund der bequemen Arbeit mit Datenbanken und Tags eine gute Lösung sein. Und auch Nicht-Entwickler können problemlos damit umgehen.

Wenn Sie mit ADR beginnen möchten, empfehle ich einen Blick in das . Dort finden Sie verschiedene ADR-Vorlagen und Beispiele für deren Verwendung.

Schritt 2 – Automatisieren

ADRs sind schwieriger zu automatisieren als Konventionen auf Codeebene: Design-Linters müssen noch erfunden werden (wie schade!). Dennoch ist es möglich, sie teilweise zu automatisieren, je nachdem, um welche Art von Vereinbarung es sich handelt.

Erstellen und aktualisieren Sie Servicevorlagen für Vereinbarungen zu Sprachen, Bibliotheken und zur Einbettung von Services in die Infrastruktur. Dann schreibt der Entwickler neue Dienste nicht von Grund auf, sondern kopiert sie aus der Vorlage und erhält sofort die konfigurierte Docker-Datei, die Veröffentlichung von Metriken usw.

Ebenso können Sie Klassengeneratoren innerhalb einer Anwendung erstellen. Angenommen, Sie hätten sich auf mehrere Anwendungsschichten geeinigt (Controller => Formular => Serviceobjekt). In diesem Fall können Sie einen einfachen Konsolenbefehl ausführen, der alle Ebenen für ein neues Feature auf einmal generiert.

Wenn Sie sich auf einige Grundsätze geeinigt haben, die auf diese Weise nicht automatisiert werden können, können Sie Checklisten organisieren, die automatisch zu einer Zusammenführungsanforderung oder einer Aufgabe im Tracker hinzugefügt werden; Somit kann der Entwickler sie schnell durchgehen, bevor er die Aufgabe weitergibt.

Vereinbarungen auf Prozessebene

In jedem Unternehmen gibt es viele Vereinbarungen für Prozesse, zum Beispiel:

• Beschreibung, wie die Einstellung im Unternehmen funktioniert.
• Beschreibung des Release-Rollout-Prozesses.
• Anforderung für Design-Reviews für große Aufgaben.
• Durchführung einer Teambesprechung zweimal pro Woche mit Besprechung aktueller Aufgaben und Hindernisse.

  
  

Bis vor Kurzem habe ich nicht daran gedacht, diese Vereinbarungen zu dokumentieren, obwohl sie den Erfolg des Unternehmens maßgeblich beeinflussen. Die Dokumentation dieser Vereinbarungen bringt nicht nur die oben genannten Vorteile mit sich, sondern ermöglicht Ihnen auch, die Prozesse zu rationalisieren, sie auf die sichtbare Ebene zu übertragen und über ihre Zweckmäßigkeit nachzudenken.

Die Idee kam mir von . Er schlug ein Tool vor, das ADR ähnelt – Process Decision Record (PDR). Der einzige Unterschied besteht darin, dass es sich nicht um architektonische Entscheidungen handelt, sondern um Entscheidungen über Prozesse. Darüber hinaus schlug er vor, in jedes PDR ein „Überarbeitungsdatum“ aufzunehmen – ein Datum, an dem Sie n Monate nach der Annahme zum Dokument zurückkehren, um zu sehen, ob es Ihre Probleme immer noch optimal löst (das Gleiche kann übrigens auch getan werden). mit ADRs).

Was die Automatisierung betrifft, können Sie wenig tun. Sie können einige Prozesse automatisieren, indem Sie einen Workflow in Jira einrichten, Erinnerungen für Besprechungen festlegen oder einen Bot erstellen, der automatisch eine Präsentation der Ergebnisse der Woche vorbereitet (ich habe dies allerdings in einem ausländischen Unternehmen gemacht).

Aber oft lassen sich Prozesse nicht wirklich automatisieren, und Ihr Hauptziel besteht darin, sie leichter verständlich zu machen als sie nicht zu befolgen. Dennoch wird die Dokumentation von Vereinbarungen immer noch hilfreich sein, auch wenn Ihre Prozesse bereits leicht zu befolgen sind – Formalisierung und Rationalisierung ermöglichen es Ihnen, sie zu verbessern.

Was ist also das Ergebnis?

Dokumentation und anschließende Automatisierung sind von Vorteil: Der Zeitaufwand für die Entwicklung sinkt, Anwendungen werden besser unterstützbar und Prozesse werden intelligenter.

Man könnte denken, dass das alles unnötige Bürokratie ist, denn „wir sind gute Leute – wir können Code ohne sie entwickeln.“ Tatsächlich sparen Sie durch Vereinbarungen jedoch viel Zeit und Geld und schonen die Nervenzellen der Mitarbeiter. Natürlich müssen Sie sich nicht auf alles einlassen und alles ablehnen, was gegen Vereinbarungen verstößt – dies kann ein Zeichen dafür sein, dass die Vereinbarung aktualisiert werden muss oder dass Sie zunächst nicht über einige ihrer Aspekte nachgedacht haben.

Wenn Sie noch nicht damit begonnen haben, Vereinbarungen in Ihrem Team zu dokumentieren, wechseln Sie von niedrigeren zu höheren Abstraktionsebenen: Beginnen Sie mit Vereinbarungen auf Codeebene, dann auf Architekturebene und beschäftigen Sie sich erst dann mit der Prozessebene. Die Dokumentation von Vereinbarungen ist für Ihr Team eine Gewohnheit, und es ist viel einfacher, mit weniger abstrakten Konzepten zu beginnen.

Darüber hinaus werden im Artikel nicht alle Typen beschrieben. Beispielsweise können Sie die Designvereinbarung als Bibliothekskomponenten dokumentieren.

Jede neue Art von Vereinbarung durchläuft dieselben drei Phasen:

1. Finden Sie heraus, wie Sie es dokumentieren.
2. Finden Sie heraus, wie Sie es automatisieren können.
3. Stellen Sie im Laufe der Zeit sicher, dass mehr Ressourcen eingespart werden, als für die Aufbewahrung erforderlich sind.

   
   

Und der Letzte. Während des Dokumentationsprozesses kann es vorkommen, dass einige der bestehenden Vereinbarungen scheinbar durch nichts gerechtfertigt sind, die Zeit Ihres Teams verschwenden und im Allgemeinen schädlich sind, Sie aber bereits daran gewöhnt sind. In diesem Fall müssen Sie die Gewohnheitsbarriere in den Köpfen des Teams überwinden und Ihr Team davon überzeugen, dass die Ablehnung von Vereinbarungen manchmal wichtiger ist als deren Annahme. Aber das ist eine ganz andere Geschichte.