Das C4-Code-Diagramm (Ebene 4) zeigt die Klassen, Schnittstellen und Funktionen innerhalb einer Komponente. Die meisten Teams sollten es überspringen -- aber nicht immer. Dieser Leitfaden behandelt, wann sich C4-Modell-Ebene 4 lohnt, wann ein UML-Klassendiagramm vergeudeter Aufwand ist und wie automatisierte Generierung das Abwägen verändert.

C4 Code Diagram (Ebene 4): Wann Sie es brauchen und wann nicht

Das Code-Diagramm ist die am meisten missverstandene Ebene des C4-Modells. Es ist die Ebene, die die meisten Teams überspringen, die Ebene, die Simon Brown selbst als optional beschreibt, und doch ist es auch die Ebene, die die meisten Fragen aufwirft: „Müssen wir wirklich unsere Klassen zeichnen?" „Ist das nicht einfach UML?" „Wer pflegt das, wenn sich der Code ändert?"

Die kurze Antwort: Meistens brauchen Sie kein C4-Code-Diagramm. Die längere Antwort ist interessanter, denn die Fälle, in denen sich Ebene 4 tatsächlich auszahlt, sind genau die Fälle, in denen Teams ohne sie am meisten Zeit verlieren -- dichte Algorithmen, regulierte Domänen und das Einarbeiten in Code, den niemand mehr vollständig versteht.

Dieser Leitfaden behandelt, was ein C4-Code-Diagramm tatsächlich zeigt, warum es fast immer ein Fehler ist, eines von Hand zu zeichnen, die konkreten Situationen, in denen C4-Modell-Ebene 4 sich lohnt, und wie automatisierte Generierung die Kosten-Nutzen-Rechnung vollständig umdreht.

Wenn Sie mit dem C4-Modell noch nicht vertraut sind, beginnen Sie zuerst mit unserem vollständigen Leitfaden zum C4-Modell -- dieser Artikel setzt voraus, dass Sie die vier Ebenen kennen.

Was ist ein C4-Code-Diagramm?

Das Code-Diagramm ist Ebene 4 des C4-Modells -- die tiefste Zoom-Ebene. Während das Component-Diagramm (Ebene 3) die wichtigsten Bausteine innerhalb eines Containers zeigt, zoomt das Code-Diagramm in eine einzelne Komponente hinein und zeigt ihre Details auf Implementierungsebene:

Klassen und ihre Beziehungen (Vererbung, Komposition, Abhängigkeit)
Schnittstellen und die Typen, die sie implementieren
Funktionen und Methoden, einschließlich wichtiger Signaturen
Datenstrukturen wie Entities, Value Objects und DTOs

In der Praxis wird ein C4-Ebene-4-Diagramm meist als UML-Klassendiagramm oder als Entity-Relationship-Diagramm dargestellt. Das C4-Modell schreibt für diese Ebene keine Notation vor -- es delegiert ausdrücklich an bestehende Standards, weil das Problem, Klassen zu zeichnen, vor Jahrzehnten gelöst wurde.

Zwei Eigenschaften definieren die Code-Ebene:

Umfang: eine Komponente. Ein Code-Diagramm umspannt nie einen ganzen Container, geschweige denn ein System. Es öffnet genau eine Komponente -- das OrderRepository, den PaymentService -- und zeigt, was darin ist.
Granularität: echte Code-Symbole. Jede Box auf einem Code-Diagramm entspricht einer tatsächlichen Klasse, Schnittstelle oder Funktion im Quellcode. Es bleibt keine Abstraktion übrig. Das ist die Ebene, auf der das Diagramm und der Code dasselbe sein sollen.

Genau diese zweite Eigenschaft ist der Grund, warum Ebene 4 so oft übersprungen wird, wie wir sehen werden. (Für eine schnelle Referenz siehe den Code-Diagramm-Eintrag in unserem Glossar.)

Simon Browns eigene Empfehlung: Zeichnen Sie es nicht

Hier ist der Teil, der Leute überrascht, die zum ersten Mal auf das C4-Modell stoßen: Sein Schöpfer rät davon ab, Code-Diagramme von Hand zu erstellen. Simon Browns Leitlinie ist, dass Ebene 4 optional ist, und wenn Sie sie brauchen, sollte sie bei Bedarf aus dem Quellcode generiert werden -- durch Ihre IDE, durch Dokumentations-Tooling oder durch alles andere, das den tatsächlichen Code liest -- statt von Hand gezeichnet und gepflegt zu werden.

Die Begründung ist schwer zu widerlegen:

Code ändert sich ständig. Ein handgezeichnetes Klassendiagramm ist ungefähr so lange korrekt, wie jemand braucht, um den nächsten Pull Request zu mergen. Jede Umbenennung, jede extrahierte Methode, jedes neue Feld macht es ein wenig falscher.
Die Information existiert bereits. Anders als ein Container-Diagramm -- das Entscheidungen festhält, die in niemandes Kopf und keiner einzelnen Datei stehen -- dupliziert ein Code-Diagramm das, was der Quellcode bereits präzise angibt.
Tooling macht es besser. Moderne IDEs (IntelliJ, Visual Studio und Konsorten) generieren Klassendiagramme aus Code in Sekunden. Sie sind immer korrekt, weil sie abgeleitet und nicht gezeichnet sind.

Die Standardposition für jedes Team, das C4 einführt, sollte also sein: Ebenen 1-3 modellieren, Ebene 4 bei Bedarf generieren. Context-, Container- und Component-Diagramme erfassen Wissen, das nicht im Code steht. Die Code-Ebene ist der Code.

Wann ein C4-Code-Diagramm sich tatsächlich lohnt

„Meistens überspringen" ist nicht „immer überspringen". Es gibt echte Situationen, in denen sich eine Ansicht auf Code-Ebene ihren Platz in Ihrer Dokumentation verdient.

1. Komplexe Algorithmen und verschachtelte Designs

Manche Komponenten implementieren Logik, die wirklich schwer zu verfolgen ist, wenn man Dateien von oben nach unten liest: eine Preisengine mit verketteten Strategien, eine State Machine, die Bestell-Lebenszyklen steuert, ein Parser mit einer tiefen Visitor-Hierarchie. Wenn die Struktur des Codes die eigentliche Erkenntnis ist -- wenn das Verständnis, welche Klasse an welche delegiert, die ganze Schlacht ist -- komprimiert ein Code-Diagramm Stunden des Code-Lesens in ein einziges Bild.

Der Test: Wenn ein erfahrener Ingenieur ein Whiteboard braucht, um die Komponente einem anderen erfahrenen Ingenieur zu erklären, dann ist diese Whiteboard-Skizze ein Code-Diagramm, das darauf wartet, festgehalten zu werden.

2. Regulierte und auditierte Domänen

In Finanzwesen, Gesundheitswesen, Luftfahrt und anderen regulierten Branchen verlangen Prüfer und Gutachter oft Dokumentation auf Implementierungsebene: welche Klasse Karteninhaberdaten verarbeitet, wo Verschlüsselung angewendet wird, wie der Audit-Trail geschrieben wird. Hier ist ein Ebene-4-Diagramm kein Nice-to-have -- es ist Beweismittel. Dasselbe gilt für Security-Reviews und Threat Modeling, bei denen der Datenfluss durch bestimmte Klassen zählt.

3. Einarbeiten in dichten, langlebigen Code

Legacy-Komponenten mit Jahren angesammelter Entscheidungen sind brutal für Neueinsteiger. Ein Code-Diagramm der drei oder vier furchteinflößendsten Komponenten Ihrer Codebasis -- jene, in denen Tribal Knowledge konzentriert ist -- kann die Einarbeitungszeit dramatisch verkürzen. Neue Entwickler sehen die Gestalt der Komponente, bevor sie in ihre 8.000 Zeilen eintauchen.

4. Öffentliche Verträge und Entwurfsmuster dokumentieren

Wenn eine Komponente eine API-Oberfläche bereitstellt, gegen die andere Teams entwickeln, oder ein Muster implementiert (Strategy, Observer, hexagonale Ports-and-Adapters), bei dem die Struktur die Dokumentation ist, macht eine Ansicht auf Code-Ebene den Vertrag explizit.

Wann Sie es nicht brauchen (was meistens der Fall ist)

Seien Sie ehrlich über die umgekehrten Fälle, denn sie decken die Mehrheit der Komponenten in jedem System ab:

Der Code ist lesbar. Eine gut benannte Komponente mit klaren Packages braucht kein Diagramm. Der Ordnerbaum ist das Diagramm.
Ebene 3 beantwortet die Frage bereits. Wenn jemand fragt „wie spricht der Order Service mit Payments?", ist das eine Frage für das Component-Diagramm. Klassen zu zeichnen fügt Rauschen hinzu, kein Signal.
Die Komponente ist simples CRUD. Ein Handler, ein Service, ein Repository, ein Model. Diese Gestalt hat jeder schon tausendmal gesehen. Sie auf Klassenebene zu dokumentieren dokumentiert nichts.
Niemand hat danach gefragt. Dokumentation sollte Fragen beantworten, die Menschen tatsächlich haben. Wenn nie jemand eine Klassenebenen-Ansicht einer Komponente gebraucht hat, ist es Aufwand für Regalware, eine zu erstellen.

Das leitende Prinzip aus dem breiteren C4-Ansatz gilt hier mit voller Wucht: Jedes Diagramm, das Sie erstellen, ist ein Diagramm, das Sie pflegen müssen. Auf den Ebenen 1-3 erkauft Ihnen die Pflegekosten Wissen, das nirgendwo sonst existiert. Auf Ebene 4 erkauft sie Ihnen meist eine etwas hübschere, etwas veraltete Kopie Ihres Quellcodes.

Wie automatisierte Generierung die Gleichung verändert

Alles oben setzt voraus, dass jemand das Diagramm zeichnen und pflegen muss. Diese Annahme machte Simon Browns Rat „überspringen oder generieren" zur richtigen Entscheidung -- die Kosten manueller Ebene 4 rechtfertigten den Nutzen fast nie.

Automatisierung beseitigt die Kostenseite dieser Gleichung. Die AI Discovery von Archyl analysiert Ihr verbundenes Repository und extrahiert Elemente auf Code-Ebene -- Klassen, Schnittstellen und Funktionen -- direkt aus dem Quellcode und hängt sie an die richtigen Komponenten in Ihrem C4-Modell. Statt dass ein Entwickler PaymentService und seine Kollaboratoren in einem Diagrammwerkzeug zeichnet, wird das Modell aus dem befüllt, was tatsächlich in der Codebasis existiert, und bleibt mit dem Repository verbunden, aus dem es stammt.

Das verändert die Frage von „lohnt sich die Pflege von Ebene 4?" zu „lohnt es sich, Ebene 4 zu haben?" -- eine viel leichter zu nehmende Hürde. Wenn die Ansicht auf Code-Ebene generiert und aktualisiert statt von Hand gezeichnet wird:

Sie lügt nie, weil sie aus dem Quellcode abgeleitet ist und nicht aus jemandes Erinnerung an den Quellcode.
Sie ist im Kontext navigierbar: Sie steigen in einem Modell von System zu Container zu Komponente zu Code hinab, statt in einem Wiki nach einer PNG zu suchen.
Die Fälle, die „trotz der Kosten lohnenswert" waren (Audits, Onboarding, komplexe Komponenten), werden trivial lohnenswert, und die Grenzfälle werden kostenlos.

Sie wenden weiterhin Urteilsvermögen darauf an, welche Komponenten auf Ebene 4 Aufmerksamkeit verdienen -- eine generierte Ansicht einer trivialen CRUD-Komponente ist immer noch Rauschen. Aber der Fehlermodus verschiebt sich von „veraltetes Diagramm führt das Team in die Irre" zu „ungenutzte Ansicht, die nichts kostet".

Ein durchgearbeitetes Beispiel: Innerhalb einer Zahlungsverarbeitungs-Komponente

Machen wir das konkret. Angenommen, Ihr Component-Diagramm (Ebene 3) zeigt eine PaymentProcessor-Komponente innerhalb Ihres Backend-API-Containers. Hineinzoomen auf Ebene 4 könnte enthüllen:

[PaymentService (interface)]
  ├── ProcessPayment(order, method) -> PaymentResult
  └── RefundPayment(paymentID, amount) -> RefundResult

[StripePaymentService] ──implements──> [PaymentService]
[StripePaymentService] ──uses──> [StripeAdapter] : wraps the Stripe SDK
[StripePaymentService] ──uses──> [RetryPolicy] : exponential backoff, 3 attempts
[StripePaymentService] ──uses──> [PaymentRepository] : persists payment records

[StripeAdapter] ──maps──> [PaymentResult] : translates Stripe responses to domain types
[RetryPolicy] ──raises──> [PaymentFailedError] : after exhausting retries
[PaymentRepository] ──persists──> [Payment (entity)]

Beachten Sie, was diese Ansicht beantwortet, was Ebene 3 nicht kann:

Wo ist die Naht zum Testen? PaymentService ist eine Schnittstelle; Tests können einen Fake einsetzen, ohne Stripe zu berühren.
Wo würde ein zweiter Anbieter eingestöpselt? Ein PaypalPaymentService, der dieselbe Schnittstelle implementiert -- die Struktur macht den Erweiterungspunkt offensichtlich.
Was passiert bei einem Fehler? Die RetryPolicy-Klasse besitzt das Backoff-Verhalten; PaymentFailedError ist der Eskalationspfad. Ein Prüfer, der fragt „was passiert, wenn eine Belastung fehlschlägt?", bekommt aus dem Diagramm eine Antwort.
Was berührt die Datenbank? Nur PaymentRepository. Der Fluss von Karteninhaberdaten ist nachverfolgbar, was in einer PCI-relevanten Komponente enorm zählt.

Das ist eine Komponente, bei der sich Ebene 4 auszahlt: Sie ist finanziell sensibel, die Fehlerbehandlung ist nicht offensichtlich, und mehrere Klassen arbeiten in einem bewussten Muster zusammen. Stellen Sie sie etwa einem UserProfileHandler gegenüber, der einen Profildatensatz liest und schreibt -- diesen auf Klassenebene zu zeichnen würde Ihnen nichts sagen, was der Dateibaum nicht schon tut.

Häufige Fehler bei C4-Ebene 4

Klassendiagramme von Hand pflegen

Der klassische Fehlschlag. Ein motivierter Ingenieur zeichnet wunderschöne Klassendiagramme für die gesamte Codebasis; sechs Monate später beschreiben sie eine Codebasis, die nicht mehr existiert, und jetzt führen sie aktiv in die Irre. Wenn ein Code-Diagramm nicht aus dem Quellcode generiert wird -- oder zumindest planmäßig neu generiert wird -- behandeln Sie es als am Tag seiner Erstellung abgelaufen.

Getter, Setter und Boilerplate dokumentieren

Ein Code-Diagramm, das jeden Accessor, jede Konstruktor-Überladung und jede Utility-Methode auflistet, hat dasselbe Problem wie eine Karte im Maßstab 1:1. Beziehen Sie die Elemente ein, die Designabsicht tragen -- Schnittstellen, Schlüsselkollaborationen, die Methoden, die den Vertrag definieren -- und lassen Sie das Zeremoniell weg. Generierte Ansichten sollten gefiltert, nicht abgekippt werden.

Ebene 4 verwenden, wo Ebene 3 genügt

Wenn Ihr „Code-Diagramm" Dinge zeigt wie „der Controller ruft den Service auf, der das Repository aufruft", haben Sie ein Component-Diagramm mit klassenförmigen Boxen gezeichnet. Klappen Sie es zurück auf Ebene 3. Reservieren Sie Ebene 4 für Komponenten, deren interne Struktur der interessante Teil ist.

Den ganzen Container auf Klassenebene zeichnen

Ein Diagramm mit 200 Klassen, das einen ganzen Service umspannt, verletzt die C4-Hierarchie und ist ohnehin unlesbar. Ein Code-Diagramm deckt eine Komponente ab. Wenn Sie es nicht so eng eingrenzen können, müssen die Komponentengrenzen in Ihrem Ebene-3-Diagramm wahrscheinlich überdacht werden.

Ebene 4 als verpflichtend für „vollständige" Dokumentation behandeln

Manche Teams führen C4 mit Checklisten-Mentalität ein: vier Ebenen, also vier Sätze von Diagrammen. Das Ergebnis ist vergeudeter Aufwand und Groll gegen die gesamte Praxis. C4 macht ausdrücklich klar, dass Ebene 4 optional ist. Drei gut gepflegte Ebenen schlagen jedes Mal vier vergammelnde.

FAQ

Ist C4-Ebene 4 einfach ein UML-Klassendiagramm?

Größtenteils ja -- und das ist so beabsichtigt. Das C4-Modell definiert keine eigene Notation für die Code-Ebene; es empfiehlt, bestehende wiederzuverwenden, und ein UML-Klassendiagramm ist die häufigste Wahl (ER-Diagramme funktionieren für datenzentrische Komponenten). Was C4 hinzufügt, ist Scoping und Kontext: Das Klassendiagramm beschreibt genau eine Komponente, und diese Komponente sitzt innerhalb einer navigierbaren Hierarchie von Container- und System-Diagrammen. Ein eigenständiges UML-Klassendiagramm schwebt frei; ein C4-Code-Diagramm hat eine Adresse.

Sollte ich für jede Komponente ein Code-Diagramm erstellen?

Nein. Die meisten Komponenten sind einfach genug, dass der Quellcode die beste Dokumentation ist. Reservieren Sie Ebene 4 für Komponenten, die algorithmisch komplex, security- oder compliance-sensibel oder berüchtigte Onboarding-Hürden sind. Wenn Dokumentation automatisch generiert wird, sinken die Kosten für mehr Abdeckung -- aber Aufmerksamkeit ist trotzdem endlich, also kuratieren Sie, was Sie sichtbar machen.

Wie halte ich ein Code-Diagramm aktuell?

Indem Sie es nicht von Hand pflegen. Generieren Sie es: aus Ihrer IDE bei Bedarf, aus Dokumentations-Tooling in der CI oder aus einer Plattform wie Archyl, die während der AI Discovery Klassen, Schnittstellen und Funktionen aus Ihrem Repository extrahiert und die Code-Ebene an Ihr Komponentenmodell angehängt hält. Jeder Prozess, der darauf angewiesen ist, dass sich ein Mensch nach einem Refactoring daran erinnert, ein Klassendiagramm zu aktualisieren, wird scheitern.

Was ist der Unterschied zwischen einer Komponente und einem Code-Element in C4?

Eine Komponente (Ebene 3) ist eine logische Gruppierung mit einer einzigen Verantwortlichkeit -- „der Teil, der Zahlungen behandelt" -- und kann sich über mehrere Klassen und Dateien erstrecken. Ein Code-Element (Ebene 4) ist ein tatsächliches Symbol im Quellcode: eine bestimmte Klasse, Schnittstelle oder Funktion. Komponenten sind Abstraktionen, die Sie wählen; Code-Elemente sind Fakten, die der Compiler erzwingt.

Das Fazit

Das C4-Code-Diagramm ist die Ebene, die Sie standardmäßig überspringen und bewusst einsetzen sollten. Die Ebenen 1-3 erfassen architektonisches Wissen, das nirgendwo sonst existiert; Ebene 4 spiegelt das wider, was der Code bereits sagt, also verdient sie sich nur dann einen Platz, wenn die Struktur selbst der schwierige Teil ist -- komplexe Algorithmen, regulierte Komponenten, dichter Legacy-Code -- und idealerweise, wenn sie generiert statt gezeichnet wird.

Wenn Sie Ansichten auf Code-Ebene ohne die Pflegesteuer wollen, verbinden Sie ein Repository mit Archyl und lassen Sie die AI Discovery die Klassen, Schnittstellen und Funktionen automatisch in Ihr C4-Modell extrahieren. Sie bekommen die Tiefe, wenn Sie sie brauchen, und niemand muss jemals wieder ein Klassendiagramm neu zeichnen.

Möchten Sie eine Ebene höher? Lesen Sie den Leitfaden zum C4-Component-Diagramm, frischen Sie Ihr Wissen mit dem vollständigen C4-Modell-Leitfaden auf oder erkunden Sie die C4-Modell-Übersicht. Bereit, es auszuprobieren? Starten Sie kostenlos mit Archyl.

C4 Code Diagram (Ebene 4): Wann Sie es brauchen und wann nicht - Archyl Blog