Zyklomatische Komplexität im Rollout-Risiko-Gating

Die zyklomatische Komplexität zählt unabhängige Pfade durch eine Funktion. NIST setzt die sichere Obergrenze bei 10 pro Funktion, und die meisten Teams setzen einen ähnlichen Wert in CI durch. Was diese Zahl nicht verrät: welche dieser Pfade tatsächlich von dem Canary ausgelöst werden, den Sie gerade auf 5 % des Produktiv-Traffics losschicken, und genau diese Lücke ist der Ort, wo die meisten Rollout-Incidents beginnen. Behandeln Sie zyklomatische Komplexität als Rollout-Risiko-Input, nicht als Lint-Regel, und die Zahl fängt an, ihren Wert zu beweisen.

Was zyklomatische Komplexität wirklich misst

McCabes Metrik ist ein Graphen-Zähler: Knoten, Kanten, verbundene Komponenten. Jedes if, for, while, case und jeder boolesche Operator fügt einen Pfad hinzu. Eine Funktion mit einer Komplexität von 25 hat mindestens 25 linear unabhängige Pfade. Das ist keine Meinung, es ist die Mathematik der Basis-Pfad-Tests, und sie setzt eine untere Grenze: Wie viele Testfälle bräuchten Sie, um die Funktion einmal, von Anfang bis Ende, abzudecken? Sourcegraphs Aufschlüsselung hat die vollständigen Schwellwerte: 1-10 niedriges Risiko, 11-20 moderat, 21-50 hoch, 50+ ist die Stufe "wir sollten darüber sprechen".

Die meisten Teams erreichen diese untere Grenze nicht. Abdeckungs-Tools berichten Zeilen-Abdeckung, keine Pfad-Abdeckung, daher kann eine Funktion 90% Abdeckung anzeigen, während die Hälfte ihrer Verzweigungen in CI nie abgefeuert werden. Das ist der Teil, den niemand in die PR-Vorlage schreibt, und es ist der Grund, warum "Tests bestanden" und "das ist sicher zu verschiffen" zwei verschiedene Aussagen sind, die als eine behandelt werden.

Wir haben genug Post-Mortems analysiert, um das Muster zu erkennen: Der Incident-Bericht hat immer eine Zeile für Error-Budget-Verbrauch und eine für Erkennungszeit. Es hat fast nie eine Zeile für das, wie die Komplexität der geänderten Funktion vor dem Diff-Merge aussah. Das ist eine Lücke in der Dokumentation, nicht nur in der Werkzeug-Landschaft.

Warum ein flacher Komplexitäts-Wert das wahre Blast-Radius verdeckt

Hier ist der Teil, den jedes Komplexitäts-Dashboard falsch macht: Zwei Funktionen können identische Komplexitäts-Werte ausgeben und dabei sehr unterschiedliche Risiken tragen. Eine 20-Verzweigungen-Switch-Anweisung, die zu gut-getesteten Handlern verteilt, ist nicht das gleiche Tier wie eine Funktion mit vier separaten Taschen verschachtelter Bedingungen, verstreut über 80 Zeilen, jede drei Ebenen tief. CodeScene nennt diese zweite Form einen "holperigen Weg", und der Name ist akkurat. Es ist die Verschachtelungs-Tiefe, nicht die rohe Verzweigungszahl, die die Arbeitsbelastung verschärft und die Edge Cases verbirgt, an die niemand dachte zu testen. CodeScenes Artikel geht in Detail durch den Vergleich, und er passt sauber zu dem, was wir in Rollout-Daten sehen.

Das ist für uns spezifisch wichtig, weil ein Canary nicht auf durchschnittliche Komplexität fehlschlägt. Er schlägt auf die eine holperige Funktion fehl, die in diesem Diff berührt wurde, um 2 Uhr morgens, unter einer Last, die niemand load-getestet hat. In den Post-Mortems, die wir mit Platform-Teams durchgesehen haben, wiederholt sich das Muster: Die Root-Cause-Funktion hat fast nie den höchsten Komplexitäts-Score im Repo. Sie hat das höchste Komplexitäts-Delta in dem Diff, der versandt wurde. Das ist ein anderes Signal, und fast niemand instrumentiert es.

Ein Dashboard, das Ihnen sagt, dass die Komplexität des Codebases sinkt, ist nicht das gleiche Dashboard, das Ihnen sagt, dass dieser Rollout, jetzt gerade, eine Funktion berührte, die gerade drei neue verschachtelte Verzweigungen hinzufügte. Eins ist ein Gesundheitsbericht, den Sie einmal im Quartal lesen. Das andere ist ein Gate, das Sie tatsächlich in der Deploy-Pipeline wollen, neben der SLO-Prüfung, nicht vergraben in einem separaten Statik-Analyse-Tool, das niemand während eines Incidents öffnet.

Ring-basierte und Prozentual-basierte Rollouts gehen bereits davon aus, dass einige Diffs risikoreicher sind als andere; das ist die ganze Prämisse eines Canary. Was die meisten Pipelines nicht tun: Sie lassen nicht die Komplexitäts-Form des Diff selbst beeinflussen, wie schnell dieser Canary sich verbreitern soll. Es wird als Code-Review-Problem behandelt, dann vergessen, sobald der PR merged.

Das CI-Gate, das jeder auf 10 setzt, und warum es nicht funktioniert

Der Standard-Rat, zyklomatische Komplexität auf 10 begrenzen und den Build darüber fehlschlagen lassen, ist der "Skip"-Schritt, den fast jeder Engineering-Blog empfiehlt und den fast niemand gegen echte Incident-Daten validiert. Es ist nicht falsch, genau. Es ist unvollständig auf eine Weise, die Teams glauben lässt, sie hätten das Risiko gehandhabt, wenn sie es hauptsächlich nur verlegt haben.

Zwei Fehlermodi, beide häufig in Teams, mit denen wir gesprochen haben:

• Die Zahl gamen. Extract Method ist die Lehrbuch-Lösung, und sie funktioniert: Komplexität pro Funktion sinkt. Aber wenn die Extraktion die tatsächliche Entscheidungszahl nicht reduziert, nur über drei Funktionen statt einer verlegt, ist die Komplexität des Systems unverändert. Das Gate wird grün. Der Blast-Radius schrumpft nicht, er ist nur schwerer in einer einzelnen Diff-Ansicht zu sehen.

• Die Form ignorieren. Ein flacher Schwellwert behandelt einen 12-Verzweigungen-Dispatcher und einen 12-Pfad-holperigen Weg als gleich riskant. Das stimmt nicht. Der Dispatcher ist wahrscheinlich ok; er ist mechanisches Routing. Der holperige Weg ist, wo Ihr nächstes Rollback lebt, weil die Person, die ihn überprüfte, nach drei verschachtelten Ebenen nicht mehr tracking konnte.

KI-Coding-Agenten machen das schlimmer, bevor sie es besser machen. Devin und ähnliche autonome Agenten verschiffen PRs schnell, und "schnell" bedeutet oft, einen Ast hinzuzufügen statt den existierenden refaktorieren. Das ist der Pfad des geringsten Widerstands für ein Modell, das für eine bestehende Test-Suite optimiert, nicht für Reviewer-Kognitive Last. Wenn Ihr Team AI-geschriebene Diffs in Volumen merged, ist Komplexitäts-Delta pro PR eine Metrik, die Sie vor dem Incident-Review auf dem Dashboard haben wollen, nicht danach.

Was das Komplexitäts-Delta wirklich über Test-Aufwand verrät

Vergessen Sie den absoluten Score für einen Moment. Die Zahl, die Incident-Risiko vorhersagt, ist die Komplexitäts-Veränderung durch einen einzelnen Diff, gegengerechnet gegen ob die Tests, die diesen Diff berühren, tatsächlich dazu wuchsen.

Eine Funktion, die in einem PR von Komplexität 8 auf 19 geht, hat, nach der Basis-Pfad-Test-Mathematik oben, ihre Mindest-Test-Zahl ungefähr verdoppelt. Wenn der PR zwei Tests hinzufügte, haben Sie eine Abdeckungs-Lücke versandt, die als Pass-CI-Lauf verkleidet ist. Diese Lücke zeigt sich nicht, bis der Canary die 5%-Traffic-Scheibe trifft, die den ungetesteten Pfad ausübt, und danach ist es ein Incident, nicht ein Code-Review-Kommentar, der ungelöst in einem PR-Thread sitzt.

Das ist die Instrumentierungs-Lücke, die das upstreamapi AI Pilot auf der Rollout-Seite schließen soll: Gate die Canary-Prozentuale und Hold-Zeit auf dem Komplexitäts-Delta des versendeten Diff, gegengerechnet gegen sein Test-Delta, nicht nur auf der Downstream Error-Rate-SLO. Eine Error-Rate-SLO sagt Ihnen, dass etwas bereits fehlgeschlagen ist. Ein Komplexitäts-Delta-Gate sagt Ihnen, dass der Diff wahrscheinlicher war, etwas zu brechen, bevor er Live-Traffic bediente, was der einzige Punkt ist, an dem diese Information noch handlungsfähig ist.

// Vereinfachtes Canary-Gate: Widen langsam auf niedrig-Risiko-Diffs, Hold auf hoch-Risiko
function canaryStep(diff: DiffMetrics): CanaryDecision {
  const complexityRisk = diff.complexityDelta / Math.max(diff.testDelta, 1);

  if (complexityRisk > 3 && diff.slo.errorBudgetBurn > 0.1) {
    return { action: "hold", trafficPct: diff.currentTrafficPct };
  }
  if (complexityRisk > 3) {
    return { action: "extend_bake_time", bakeMinutes: 45 };
  }
  return { action: "advance", trafficPct: diff.currentTrafficPct + 10 };
}

Stimmt die Forschung damit überein?

Nein, und das ist es wert zu sagen. Einige Praktiker-Forschung widersprechen hard zyklomatischer Komplexität als Defekt-Prädiktor überhaupt, argumentierend Teams, die für einen niedrigeren Score optimieren, verlegen Komplexität einfach irgendwo weniger Sichtbar. GetDX Kritik macht diesen Fall und zeigt Teams in Richtung Developer-Experience-Metriken statt. Wir denken, dieser Argument tötet die Metrik nicht; wir denken, es tötet die Metrik in Isolation verwendet, als eine statische Repo-breite Wertung, getrennt vom Diff und dem Rollout, an den es angebunden ist.

Wie man einen Canary tatsächlich auf Komplexität gatet, nicht nur auf Error-Rate

Drei Dinge, in der Reihenfolge der Reibung, die sie zu einem PR hinzufügen:

1. Komplexitäts-Delta pro Diff berechnen, nicht pro Repo. Repo-breite Durchschnitte verbergen die eine Funktion, die diese Woche wichtig ist. Delta pro PR ist billig zu berechnen in den meisten Statik-Analyse-Tools, und es ist die Zahl, die mit dem korreliert, was tatsächlich in den nächsten 48 Stunden bricht.

2. Gegen Test-Delta gegenrechnen, nicht Test-Zahl. Eine Funktion mit 40 Tests und einem Komplexitäts-Sprung von 8 zu 19 mit null neuen Tests ist ein größeres Risiko als eine frische Funktion mit Komplexität 15 und übereinstimmender Abdeckung von Tag eins.

3. Das Verhältnis in Rollout-Pacing einfügen, nicht nur Merge-Genehmigung. Ein hohes Komplexitäts-Delta-Diff muss nicht bei Überprüfung blockiert werden; viel legitim komplexe Domänen-Logik (State-Maschinen, Protokoll-Parser) wird immer high scoren. Es braucht einen langsameren Canary und eine kürzere Error-Budget-Leine, was eine Rollout-Entscheidung ist, nicht eine Code-Review-Entscheidung.

Schreiben Sie den Runbook-Eintrag vor dem Rollout, nicht nach dem Seite. Wenn der On-Call-Ingenieur, der um 3 Uhr morgens den Incident-Kanal öffnet, reverse-engineeren muss, warum ein "sauberer" PR gerade das Error-Budget verbrannt hat, ist die Dokumentation gescheitert, bevor der Code es tat. Eine Ein-Zeiler im Deploy-Log ("Komplexitäts-Delta 11, Test-Delta 1, gehalten bei 20%") kostet nichts zu schreiben und spart die ersten fünfzehn Minuten jedes Incident-Reviews, das folgt.

Ist es wert zu tracking, oder einfach eine weitere Dashboard-Zahl?

Kommt drauf an, wo Sie es anbinden. Zyklomatische Komplexität als eine Repo-Health-Trendlinie ist meist Deko: nett für eine Quarterly Slide, nutzlos um 2 Uhr morgens. Zyklomatische Komplexität als ein Pro-Diff-Delta, eingefüttert in Canary-Pacing und gegengerechnet gegen Test-Wachstum, ist einer der billigeren Früh-Indikatoren, die wir gefunden haben für "dieser Rollout wird jemanden anrufen."

Der Post-Mortem wird fragen, wie das SLO-Budget vor dem Rollback aussah. Zunehmend fragt der Unsere auch, wie das Komplexitäts-Delta auf dem Diff aussah, der versandt wurde. Es lohnt sich, diese Frage zu Ihrem eigenen Runbook hinzuzufügen, bevor ein Incident die Konversation erzwingt, nicht während des Retro, wenn die Antwort ein Schulterzucken und ein Versprechen ist, "nächstes Mal bessere Tests zu schreiben."