[Semester 4] Woche 8 & 9 - Technical Review & Retrospektive

[Moritz-Czekalski]

Technical Review

Datum und Zeitrahmen

• Datum: 26.05.2026
• Start: 16:00 Uhr
• Ende: 18:13
• Dauer: 133 Minuten

Teilnehmer

Rolle	Name
Externer Reviever	Philip Röttgen
Review-Team	Simon Just
Review-Team	Florian Blum
Review-Team	Moritz Czekalski
Protokoll	Mohid Syed

Ziel und Fokus des Reviews

Ziel des Reviews ist es, einen begrenzten, aber für den Projekterfolg zentralen Ausschnitt von BitFlow technisch zu bewerten. BitFlow ist ein Softwareprojekt im Bereich digitaler Schaltungen. Der betrachtete Ausschnitt betrifft insbesondere die Simulation von Schaltungen sowie die Verwaltung und Darstellung von Gate- und Pin-Strukturen.

Der Fokus liegt daher nicht auf dem gesamten Repository, sondern bewusst auf dem Simulation Core und der Gate-Bibliothek. Diese Komponenten sind besonders relevant, weil sie direkt beeinflussen, ob eine vom Nutzer erstellte Schaltung fachlich korrekt ausgewertet und verständlich dargestellt wird. Fehler in diesen Bereichen können dazu führen, dass die Anwendung falsche Simulationsergebnisse liefert, bei bestimmten Schaltungen instabil wird oder für zukünftige Erweiterungen schwer wartbar bleibt.

Die Auswahl orientiert sich an den Review-Guidelines aus der Vorlesung: Es wurden kritische Komponenten priorisiert, insbesondere Kernfunktionalität, komplexere Logik und potenzielle Hochrisikostellen im Hinblick auf Korrektheit, Wartbarkeit und Stabilität.

Auswahl des Projektquellcodes

Komponente	Datei	Grund der Auswahl
Netzanalyse / Union-Find	evaluateCircuit.ts	Gruppiert verbundene Pins und Wires zu logischen Netzen. Fehler wirken sich direkt auf alle Simulationsergebnisse aus.
Signalauswertung	evaluateCircuit.ts	Berechnet die logischen Signalwerte der Schaltung. Besonders relevant bei mehreren Ausgängen, offenen Eingängen und Rückkopplungen.
Iterative Simulation	evaluateCircuit.ts	Verantwortlich für das Erreichen eines stabilen Zustands. Wichtig für komplexere oder rückgekoppelte Schaltungen.
Flip-Flop-Auswertung	evaluateCircuit.ts	Zustandsbehaftete Logik ist besonders fehleranfällig, da Reihenfolge und Taktverhalten korrekt behandelt werden müssen.
Custom Gates	evaluateCircuit.ts	Ermöglicht benutzerdefinierte Logik über Wahrheitstabellen. Wichtig für Erweiterbarkeit und fachliche Flexibilität.
Gate-Templates	gateLibrary.ts	Zentrale Definition der verfügbaren Gatter und ihrer Eigenschaften. Wichtig für Wartbarkeit und Erweiterbarkeit.
Pin-Erzeugung und Layout	gateLibrary.ts	Bestimmt Anzahl, Position und Beschriftung von Pins. Fehler beeinflussen Bedienbarkeit und visuelle Konsistenz.
Gate-Größenberechnung	gateLibrary.ts	Berechnet die passende Gate-Höhe abhängig von der Pin-Anzahl. Relevant für Stabilität und UI-Verhalten.

Review-Kriterien

Kriterium	Bedeutung im Review
Korrektheit	Liefert die Simulation fachlich korrekte Ergebnisse für kombinatorische und zustandsbehaftete Schaltungen?
Robustheit	Verhält sich der Code auch bei großen, ungünstigen oder fehlerhaft verdrahteten Schaltungen kontrolliert?
Wartbarkeit	Ist die Logik verständlich genug, um später erweitert oder korrigiert werden zu können?
Codequalität	Sind Funktionen sinnvoll strukturiert, lesbar und nachvollziehbar?
Fehlerbehandlung	Werden problematische Schaltungen, nicht konvergierende Zustände oder Verdrahtungsfehler erkennbar gemacht?
Skalierbarkeit	Funktioniert der Ansatz auch bei größeren Schaltungen ohne unnötige Performance- oder Stack-Risiken?
Benutzerfeedback	Werden mögliche Modellierungsfehler wie Floating Inputs oder Output-Output-Verbindungen für Nutzer sichtbar?
Erweiterbarkeit	Lassen sich neue Gate-Typen, Custom Gates oder zusätzliche Pin-Konfigurationen sauber integrieren?

Review-Methode

Verwendet wurde ein technisches Code Review mit Walkthrough-Charakter. Der Code wurde nicht vollständig flächendeckend geprüft, sondern anhand kritischer Komponenten schrittweise nachvollzogen. Im Mittelpunkt standen dabei folgende Fragen:

1. Wie werden Pins und Wires zu Netzen gruppiert?
2. Wie entstehen daraus logische Signalwerte?
3. Wie verhält sich die Simulation bei Rückkopplungen und zustandsbehafteten Bausteinen?
4. Wie werden Gates, Pins und Layoutinformationen erzeugt?
5. Welche Stellen sind für zukünftige Änderungen schwer verständlich oder fehleranfällig?

Diese Methode passt zum Aufgabenblatt, weil ein begrenzter Teil des Projekts bewusst ausgewählt, anhand definierter Kriterien untersucht und anschließend mit konkreten Maßnahmen dokumentiert wurde.

Ergebnisse des Reviews

Positive Beobachtungen

• Die Verwendung einer Union-Find-Struktur (DisjointSet) zur Gruppierung verbundener Netze ist für eine Schaltungssimulation ein passender und effizienter Ansatz.
• Die Simulation trennt grundsätzlich zwischen output-getriebenen Netzen und input-lesenden Pins. Das entspricht dem üblichen Modell digitaler Schaltungen.
• Die Gate-Definitionen sind über zentrale Templates organisiert. Dadurch lassen sich neue Gate-Typen vergleichsweise strukturiert ergänzen.
• Die Pin-Positionierung berücksichtigt gerade und ungerade Pin-Anzahlen sowie unterschiedliche Gate-Höhen.
• Die Logik für Custom Gates über Wahrheitstabellen ist ein starkes Erweiterbarkeitsmerkmal.
• Die bestehende Struktur zeigt bereits ein klares Domänenmodell aus Gates, Pins, Wires, Circuit und Gate-Templates.
• Die betrachteten Dateien bündeln wichtige Domänenlogik an wenigen zentralen Stellen, statt sie über viele UI-Komponenten zu verteilen.

Kritische Beobachtungen und Risiken

Komponente	Beobachtung	Bewertung	Maßnahme
DisjointSet.find in evaluateCircuit.ts	Die Pfadkompression ist rekursiv implementiert. Bei sehr langen, noch nicht komprimierten Ketten kann dadurch theoretisch der JavaScript-Call-Stack überschritten werden.	Risiko vor allem bei sehr großen oder ungünstig erzeugten Schaltungen. Im normalen Projektumfang vermutlich selten, aber vermeidbar.	Rekursive Implementierung durch eine iterative Variante mit while-Schleife ersetzen.
DisjointSet.find in evaluateCircuit.ts	Der Guard if (!parent ...) ist hauptsächlich wegen Map.get() und TypeScript nötig, obwohl der Key direkt vorher initialisiert wird.	Funktional unkritisch, aber für Leser nicht sofort nachvollziehbar.	Kurzen Kommentar ergänzen oder Code so strukturieren, dass die Typannahme klarer ist.
Netzwertberechnung in evaluateCircuit.ts	Wenn zwei Output-Pins auf dasselbe Netz treiben, wird der Wert per OR zusammengeführt. Ein potenzieller Kurzschluss bzw. Modellierungsfehler bleibt dadurch unsichtbar.	Fachlich problematisch: Output-Output-Verbindungen sind in digitalen Schaltungen meist Fehler, werden aber stillschweigend akzeptiert.	Mehrere Treiber pro Netz erkennen und Warnung oder Fehlerstatus an die UI zurückgeben.
Floating Inputs in evaluateCircuit.ts	Nicht getriebene Eingänge fallen effektiv auf false zurück.	Als Default nachvollziehbar, aber für Nutzer möglicherweise verwirrend, wenn eine Verbindung vergessen wurde.	Floating Inputs erkennen und visuell oder als Simulationswarnung anzeigen.
Iterationsgrenze in evaluateCircuit.ts	maxIterations = Math.max(4, circuit.gates.length * 5) nutzt einen festen Faktor ohne dokumentierte Begründung.	Magic Number; bei komplexen oder rückgekoppelten Schaltungen ist unklar, ob das Limit fachlich ausreicht.	Konstante benennen, dokumentieren und bei Nicht-Konvergenz einen Status/Warnhinweis zurückgeben.
Nicht-Konvergenz in evaluateCircuit.ts	Wenn kein stabiler Zustand erreicht wird, liefert die Simulation offenbar den zuletzt berechneten Zwischenstand zurück.	Kritisch, weil Nutzer ein scheinbar gültiges Ergebnis sehen könnten, obwohl die Schaltung nicht stabil ausgewertet wurde.	Rückgabewert um converged, iterations und ggf. warnings erweitern.
Flip-Flop-Auswertung in evaluateCircuit.ts	Flip-Flops schreiben ihren neuen Zustand direkt in das gemeinsame state-Objekt.	Potenziell reihenfolgeabhängiger Bug: Ein später ausgewertetes Flip-Flop kann bereits den neuen Zustand eines früher ausgewerteten Flip-Flops sehen.	Zustandsänderungen zunächst puffern und erst nach dem Simulationsschritt gesammelt anwenden.
Gate-Höhenberechnung in gateLibrary.ts	Die while-Schleife zur Höhenanpassung hat keine obere Grenze.	Mathematisch aktuell terminierend, aber bei zukünftigen Änderungen anfällig für UI-Hänger.	Sicherheitslimit ergänzen und bei Überschreitung einen klaren Fehler werfen.
Pin-Verteilungslogik in gateLibrary.ts	Die Paritätslogik für gerade/ungerade Höhen und Pin-Anzahlen ist korrekt wirkend, aber schwer intuitiv nachvollziehbar.	Wartungsrisiko: Änderungen könnten leicht unbeabsichtigte Layoutfehler erzeugen.	Kommentar, kleine Beispiele oder ASCII-Skizzen ergänzen. Zusätzlich Tests für typische Pin-Konstellationen schreiben.
Gate-Resize in gateLibrary.ts	Beim Neukonfigurieren von Pins werden neue Pin-Objekte aus Template-Daten erzeugt. Bestehende individuelle Labels können dadurch verloren gehen.	UX- und Datenverlust-Risiko, wenn Nutzer Pins individuell beschriften.	Vorhandene Labels übernehmen und nur neue Pins mit Template-Defaults initialisieren.

Detaillierte Review-Punkte

1. Rekursive Pfadkompression in DisjointSet

Die Union-Find-Struktur ist grundsätzlich eine gute Wahl, weil sie verbundene Pins effizient zu Gruppen zusammenfasst. Kritisch ist jedoch die rekursive Umsetzung der find()-Methode. Bei sehr tiefen Parent-Ketten kann Rekursion in JavaScript zu einem Stack Overflow führen.

Für den aktuellen Projektumfang ist das vermutlich kein häufiger Fehlerfall. Trotzdem ist eine iterative Variante robuster und kaum komplexer. Gerade weil diese Funktion zur Kernlogik der Simulation gehört, lohnt sich hier eine defensive Implementierung.

Empfohlene Maßnahme: find() iterativ umsetzen und die Pfadkompression anschließend explizit auf dem besuchten Pfad durchführen.

2. Erkennung von Output-Output-Verbindungen

Die aktuelle Logik fasst Ausgangswerte auf demselben Netz über ein logisches OR zusammen. Für normale Schaltungen mit genau einem Treiber pro Netz ist das unproblematisch. Sobald aber mehrere Outputs dasselbe Netz treiben, wird ein fachlicher Verdrahtungsfehler verdeckt.

Das kann zu Simulationsergebnissen führen, die zwar technisch berechenbar sind, aber nicht dem entsprechen, was ein Nutzer von einer realistischen Schaltungssimulation erwartet.

Empfohlene Maßnahme: Während der Netzanalyse zählen, welche Output-Pins ein Netz treiben. Bei mehr als einem Treiber sollte die Simulation mindestens eine Warnung erzeugen.

3. Floating Inputs

Nicht verbundene Eingänge werden implizit als false behandelt. Das ist als deterministischer Default sinnvoll, sollte aber sichtbar sein. Ein Nutzer kann sonst eine Schaltung falsch verdrahten und erhält trotzdem ein scheinbar normales Ergebnis.

Empfohlene Maßnahme: Floating Inputs in der Simulation erkennen und über die UI anzeigen, zum Beispiel als gelbes Warnsymbol am betroffenen Pin oder als Liste von Simulationswarnungen.

4. Iterationslimit und Konvergenz

Das aktuelle Iterationslimit ist abhängig von der Anzahl der Gates, aber der konkrete Faktor ist nicht begründet. Noch wichtiger ist, dass ein Nichterreichen eines stabilen Zustands nicht klar an den Nutzer zurückgemeldet wird.

Bei kombinatorischen Schaltungen mit Rückkopplungen oder bei oszillierenden Strukturen ist es fachlich wichtig zu wissen, ob die Simulation stabil konvergiert ist.

Empfohlene Maßnahme: Die Simulation sollte nicht nur Signalwerte zurückgeben, sondern auch Metainformationen wie converged, iterations und warnings.

5. Flip-Flop-Zustände und Simultanität

Die In-Place-Mutation des Flip-Flop-Zustands ist der wichtigste fachliche Review-Punkt. In realen digitalen Schaltungen übernehmen Flip-Flops ihren neuen Zustand gleichzeitig zur Taktflanke. Wenn die Software den Zustand jedoch während der Gate-Schleife direkt verändert, kann die Reihenfolge der Gates das Ergebnis beeinflussen.

Empfohlene Maßnahme: Neue Flip-Flop-Zustände während der Evaluation in einem temporären Objekt sammeln und erst nach Abschluss des Simulationsschritts in den globalen Zustand übernehmen.

6. Gate-Layout und Pin-Verteilung

Die Gate-Bibliothek enthält kompakte Logik zur Positionierung von Pins. Positiv ist, dass die Implementierung unterschiedliche Fälle berücksichtigt. Gleichzeitig ist die Logik nicht selbsterklärend, weil sie stark von Parität und geometrischer Interpretation abhängt.

Empfohlene Maßnahme: Die Funktion durch Kommentare, Beispiele und kleine Unit-Tests absichern. Dadurch wird verhindert, dass spätere Änderungen am Layout unbeabsichtigt bestehende Gate-Darstellungen beschädigen.

7. Label-Erhalt beim Resize

Wenn bei einer Gate-Konfiguration Pins neu erzeugt werden, sollten vorhandene nutzerdefinierte Labels nicht verloren gehen. Gerade bei Custom Gates oder komplexeren Schaltungen können Pin-Namen fachliche Bedeutung tragen.

Empfohlene Maßnahme: Beim Resize alte Pins positionsbasiert übernehmen und nur für neu hinzugefügte Pins auf Template-Labels zurückfallen.

Abgeleitete Maßnahmen

Priorität	Maßnahme	Nutzen
Hoch	Flip-Flop-State-Updates puffern und gesammelt anwenden.	Verhindert reihenfolgeabhängige Simulationsergebnisse.
Hoch	Nicht-Konvergenz explizit erkennen und im Simulationsergebnis zurückgeben.	Verhindert scheinbar gültige Ergebnisse bei instabilen Schaltungen.
Hoch	Output-Output-Verbindungen als Warnung oder Fehler erfassen.	Macht fachliche Verdrahtungsfehler sichtbar.
Mittel	Floating Inputs erkennen und in der UI anzeigen.	Verbessert Verständlichkeit und Fehlerdiagnose für Nutzer.
Mittel	Rekursive find()-Methode iterativ implementieren.	Erhöht Robustheit bei großen Schaltungen.
Mittel	Magic Number für Iterationslimit benennen und begründen.	Verbessert Wartbarkeit und Nachvollziehbarkeit.
Mittel	Sicherheitsgrenze für Gate-Höhenberechnung ergänzen.	Verhindert mögliche UI-Hänger bei zukünftigen Regressionen.
Mittel	Pin-Verteilungslogik kommentieren und mit Tests absichern.	Reduziert Wartungsrisiken bei Layoutänderungen.
Niedrig	TypeScript-Guard in find() kommentieren oder lesbarer gestalten.	Verbessert Codeverständlichkeit.
Niedrig	Pin-Labels beim Resize erhalten.	Verhindert UX-Probleme und unerwarteten Labelverlust.

Gelernte Best Practices

• Reviews sollten sich auf kritische Komponenten konzentrieren, statt das gesamte Projekt oberflächlich zu prüfen.
• Bei Simulationen ist nicht nur das berechnete Ergebnis wichtig, sondern auch die Information, ob das Ergebnis stabil und konfliktfrei zustande gekommen ist.
• Zustandsbehaftete Logik sollte nicht durch Auswertungsreihenfolge beeinflusst werden.
• Magic Numbers sollten benannt und begründet werden.
• Implizite Defaults wie false für offene Eingänge sind nur dann gut, wenn Nutzer sie nachvollziehen können.
• Kompakte mathematische oder geometrische Logik braucht Kommentare und Tests.
• Erweiterbare Strukturen wie Gate-Templates sind sinnvoll, sollten aber nutzerdefinierte Daten wie Labels nicht unbeabsichtigt überschreiben.
• Ein Review-Bericht sollte neben Problemen auch gute technische Entscheidungen festhalten.

Gesamtfazit

Der betrachtete Ausschnitt von BitFlow ist insgesamt sinnvoll strukturiert und zeigt mehrere gute technische Entscheidungen. Besonders positiv sind die Union-Find-basierte Netzanalyse, die zentralisierte Gate-Bibliothek und die Unterstützung benutzerdefinierter Gates. Diese Ansätze bilden eine solide Grundlage für eine erweiterbare digitale Schaltungssimulation.

Die wichtigsten Risiken liegen weniger in der allgemeinen Struktur, sondern in fachlichen Edge Cases der Simulation. Besonders relevant sind die reihenfolgeabhängige Flip-Flop-Auswertung, fehlende Rückmeldung bei Nicht-Konvergenz und das stille Zusammenführen mehrerer Output-Treiber. Diese Punkte sollten priorisiert behoben werden, weil sie direkt die fachliche Korrektheit der Simulation betreffen.

Für die weitere Projektentwicklung empfiehlt sich, das Simulationsergebnis um Warnungen und Statusinformationen zu erweitern. Dadurch könnte BitFlow nicht nur Werte anzeigen, sondern Nutzern auch erklären, warum eine Schaltung möglicherweise fehlerhaft, instabil oder unvollständig verdrahtet ist. Insgesamt ist der Review-Ausschnitt gut gewählt, weil er zentrale Kernfunktionalität, Wartbarkeit und Benutzerfeedback gleichzeitig adressiert.

---

Retrospektive

Zusammenfassung:

Erläuterung:

Continue

Die regelmäßigen Blogeinträge und die Fortschrittsdokumentation sollten wir beibehalten, weil sie den Projektverlauf nachvollziehbar machen. Auch Pull Requests mit Reviews haben geholfen, Fehler früher zu erkennen und Code nicht unkontrolliert zu mergen. SonarCloud, automatisierte Tests und CI/CD sollten ebenfalls weiter genutzt werden, da sie uns schnelles Feedback zur Codequalität, Sicherheit und Stabilität geben. Gute Kommunikation im Team war außerdem wichtig, um Aufgaben abzustimmen und Missverständnisse zu vermeiden.

Stop

Wir sollten aufhören, zu viele Features gleichzeitig zu beginnen, bevor ältere Aufgaben sauber abgeschlossen sind. Das führt schnell zu offenen Baustellen und macht das Projekt unübersichtlich. Außerdem sollten Tests nicht erst am Ende gemacht werden, weil Fehler dann schwerer und stressiger zu beheben sind. Große Codeänderungen ohne Absprache oder Review sollten ebenfalls vermieden werden. Technische Schulden, wie unsauberer Code, fehlende Tests oder Code Smells, sollten nicht zu lange liegen bleiben, da sie die Weiterentwicklung erschweren.

Invent

Für zukünftige Sprints wäre es sinnvoll, früher mit automatisierten Tests zu starten. Dadurch fallen Fehler schon während der Entwicklung auf. Außerdem sollten Aufgaben klarer verteilt werden, damit es weniger Überschneidungen gibt und jeder weiß, woran er arbeitet. Regelmäßige kleinere Reviews von Zwischenständen könnten helfen, Probleme früher zu erkennen, statt erst am Ende große Änderungen prüfen zu müssen. Auch die Dokumentation sollte parallel zur Entwicklung gepflegt werden, damit später keine wichtigen Informationen fehlen.

Act

Als nächste konkrete Schritte sollten wir zuerst das Backend weiter ausarbeiten und offene Bugs sowie technische Schulden priorisieren. Danach sollten wir die SonarCloud-Ergebnisse prüfen und wichtige Code Smells beheben. Außerdem müssen wir kontrollieren, ob alle SRS-Anforderungen erfüllt oder zumindest sauber dokumentiert sind. Besonders kritische Funktionen sollten stärker getestet werden, damit das Projekt am Ende stabiler, vollständiger und besser bewertbar ist.

[Dupl0s]

Gut strukturierter Bericht! Die Wahl des Simulation Cores als Review-Fokus war smart , gerade der Punkt mit den Flip-Flop-Updates, die direkt ins gemeinsame State-Objekt schreiben, ist ein klassischer Bug. Auch das fehlende Konvergenz-Feedback ist wichtig: Nutzer sollten wissen, ob ein Ergebnis stabil ist oder nicht. Die Retrospektive klingt ehrlich und die Act-Punkte sind konkret und realistisch. Viel Erfolg beim Abschluss!

[ifureadthishaveanicedave]

Liebes BitFlow-Team,

ich finde eure Review und Retro sehr gelungen.
gerade der Teil mit der Erläuterung der Retro zeigt, das eure Retro sinnvoll war
und ihr hier wirklich auch Learnings mit aus dem Projekt nehmen könnt.

Eure Caesar`s Gambit devs

[tinow04]

Guter Bericht. Die Ergebnisse des Reviews sind leicht verständlich.
Viele Punkte eures Retros kenne ich von unserem Projekt :)

[Nom Nom Now]