Neue Codebase, keine Panik – Strategien zum schnellen Durchblick

Hinweis: Dieser Artikel wurde unter Zuhilfenahme von KI aus dem Englischen übersetzt. Hier geht's zum Originaltext.

Als Agentur bekommen wir regelmäßig die Möglichkeit, in bestehende Codebasen einzutauchen. Manchmal ist das, wenn wir ein Projektteam unterstützen, um einen Release über die Ziellinie zu bringen, oder vielleicht machen wir ein Projekt-Audit. Jedoch können diese Momente etwas einschüchternd sein. Wie funktioniert diese App? Welche Dateien sind wichtig? Wie ist die Codequalität? Wo fange ich an?

In diesem Beitrag stellen wir vier mögliche Strategien und Tools vor, mit denen du bestehende Codebasen einfach erkunden kannst. Normalerweise dauert das weniger als 15 Minuten. Wir hoffen, dass diese Strategien auch dir helfen werden.

🚨 Bevor wir loslegen: Nähere dich einer Codebasis immer mit Empathie. Es ist leicht, vorschnell über den Stil oder die Qualität des Codes zu urteilen. Denk daran: Du kennst möglicherweise nicht den vollständigen Kontext, wann und wie das Projekt entstanden ist. Nutze auch die Gelegenheit, die Codebasis gemeinsam mit einem Kollegen zu erkunden. Vier Augen sehen mehr als zwei. Sprecht laut und ihr werdet sehen, dass ihr schnell voneinander lernen könnt.

Für diesen Beitrag schauen wir uns die fantastische App cal.com an, "Scheduling infrastructure for everyone", wie sie sagen. Es ist nicht nur ein großartiges Produkt, sondern auch ein etabliertes Open-Source-Projekt, das einige unserer Lieblingspakete verwendet – perfekt! Los geht's.

Zuerst brauchen wir den Quellcode. Klonen wir das Repository mit dem hervorragenden GitHub CLI:

Wir werfen einen schnellen Blick auf die README-Datei.

Sofort erkennst du ein gut strukturiertes Dokument, das dir hilft, die benötigten Informationen zu finden. Interessierst du dich für Entwicklung oder Deployment? Es gibt Abschnitte dafür. Besonders die Details, um das Projekt auf deinem lokalen Rechner zum Laufen zu bringen, werden oft übersehen. Das Dokument enthält auch hilfreiche Verweise auf weitere Informationen, wie den Leitfaden für Mitwirkende oder die Roadmap. Ein hervorragender Start!

💡 Worauf du achten solltest:

• Hat sich jemand Zeit genommen, die Schritte aufzulisten, um die App zum Laufen zu bringen?
• Wird der Zweck der Anwendung genannt? Verstehst du ihn?
• Verweist es auf etablierte Konventionen? Das können Code- oder Kommunikationskonventionen sein.
• Wird ein Design-System wie Storybook oder ähnliches erwähnt? Wie sieht es aus?

Wie wir alle wissen, sind Codezeilen kein gutes Maß für irgendetwas. Dennoch können sie uns etwas über die Struktur des Projekts verraten. Das wird besonders nützlich, wenn die Übersicht nach Dateityp oder Programmiersprache gruppiert werden kann. Wir verwenden gerne tokei dafür. Es ist ein in Rust geschriebenes CLI-Tool und wahnsinnig schnell.

Sofort erkennen wir, dass es sich um eine nicht-triviale Anwendung mit einer Mischung aus Sprachen und ungefähr 500.000 Codezeilen handelt. Es scheint SQL zu verwenden (wir vermuten Migrationsdateien und entsprechende Tools), kann mit Docker bereitgestellt werden und ist ansonsten hauptsächlich in TypeScript geschrieben. In diesem Stadium denken wir nicht an Qualität, da keine dieser Statistiken etwas über den Inhalt der Dateien aussagt. Wieder einmal gilt: Den Output musst du einordnen können. Wir versuchen lediglich, einen Überblick zu bekommen.

💡 Worauf du achten solltest:

• Welche Sprachen sind vorhanden?
• Gibt es eine Sprache, mit der ich nicht vertraut bin? Kann mir jemand aus dem Team helfen, wenn ich Fragen habe?
• Gibt es Codekommentare?
• Gibt es zusätzliche Dokumentation neben der README-Datei? Achte auf Markdown- und HTML-Dateien.

Schauen wir uns die package.json-Datei an. Wir können leicht erkennen, dass dieses Projekt ein Yarn-Monorepo mit mehreren Apps und Paketen ist. Es gibt eine umfangreiche Liste von Skripten, die bei der Verwaltung helfen. Anscheinend gibt es einen "App Store" und eine "Embed"-Funktion, die beide interessant klingen. Wir sehen einige schöne Entwicklungstools wie Prisma, Swagger und Storybook. Für Tests verwendet es das heilige Duo Vitest und Playwright. Developer Experience vom Feinsten. ✨

Wie bei jedem modernen Webprojekt sollten wir uns um den Abhängigkeitsbaum kümmern. Gibt es schwerwiegende Sicherheitsprobleme in den Produktionsabhängigkeiten? Wie aktuell sind die Versionen?

Werfen wir einen Blick darauf:

Mit npx taze können wir einen Überblick über veraltete Pakete bekommen:

Du kannst auch npx taze -r ausführen, um rekursiv alle package.json-Dateien zu überprüfen – sehr hilfreich in einem Monorepo-Szenario wie hier. Sieh dir die taze-Dokumentation für weitere Details an, auch wie du deine Projektabhängigkeiten einfach aktualisieren kannst.

Auch dieser Output muss man natürlich einordnen. Aber er kann uns eine Vorstellung von der Gesundheit des Projekts geben.

💡 Worauf du achten solltest:

• Gibt es Skripte für Linting und Tests? Du kannst scriptlint verwenden. Es ist ein Tool zum Prüfen des Scripts-Abschnitts deiner package.json, entwickelt von unserem eigenen Moritz Jacobs!
• Gibt es schwerwiegende Sicherheitsprobleme in den Abhängigkeiten? Du kannst npm audit verwenden.
• Wie aktuell sind die Abhängigkeiten? Du kannst taze verwenden.

Werfen wir einen Blick auf den Insights-Tab auf GitHub, insbesondere auf die Mitwirkenden-Übersicht: https://github.com/calcom/cal.com/graphs/contributors

Wir können erkennen, dass das Projekt regelmäßig über 50 Commits pro Woche auf dem Hauptzweig erhält. Mehrere verschiedene Mitwirkende arbeiten am Code, immer ein gutes Zeichen. Anscheinend begann die Entwicklung am 7. März 2021. Wir sehen auch, dass die GitHub-Apps Crowdin und Kodiak verwendet werden, um bei der Wartung des Projekts zu helfen.

Nimm dir einen Moment Zeit, um den Insights-Tab zu erkunden. Der Abschnitt Pulse ist auch interessant, um einen Eindruck von der jüngsten Aktivität zu bekommen. Die aktuellen Issues und Pull Requests können ebenfalls wichtig sein. Aber tiefer einzutauchen braucht mehr Zeit. Machen wir weiter.

💡 Worauf du achten solltest:

• Wie hoch ist die Commit-Häufigkeit?
• Wie viele Mitwirkende gibt es (in letzter Zeit)?
• Welche Apps und Bots helfen bei der Wartung des Projekts?

Es gibt viele Metriken zur Codekomplexität wie zyklomatische Komplexität oder komplexere wie COCOMO. Ein interessanter Ansatz, auf den wir gestoßen sind, ist im Paket code-complexity implementiert. Es kombiniert zwei Faktoren, die helfen, die dicken Brocken der Anwendung aufzudecken. Erstens misst es die Komplexität des JavaScript-Codes. Dies kann mit verschiedenen Strategien wie Zeilenanzahl, zyklomatischer Komplexität oder der Halstead-Komplexität erfolgen. Zweitens misst es die Churn-Rate. Diese wird berechnet, indem ermittelt wird, wie oft eine Datei in der Vergangenheit geändert wurde (durch Blick in die Git-Historie). Diese beiden Faktoren multipliziert ergeben einen Score:

Ein Blick auf die Ausgabe zeigt die Kernstücke des Projekts, wie handleNewBooking.ts oder den EventManager. Auch zod wird für die Validierung verwendet – etwas, das wir ebenfalls empfehlen.

An dieser Stelle sollte es offensichtlich sein, aber wir sagen es noch einmal: Den Output muss man natürlich einordnen. Hohe Komplexität oder hoher Churn sind nicht schlecht. Terminplanung ist ein inhärent schwieriges Problem, daher erfordert es komplexen Code. Aber um die Struktur und innere Funktionsweise des Projekts zu bewerten, können diese Metriken sehr hilfreich sein.

💡 Worauf du achten solltest:

• Welche Bereiche des Projekts finden sich im Code-Complexity-Bericht?
• Sind diese Bereiche durch Tests abgedeckt?
• Wie sehen diese Dateien aus?

Wie bei jedem komplexen Thema haben wir hier nur einen kleinen Einblick bekommen. Es gibt noch so viel mehr, was wir nicht angeschaut haben:

• Blick in die Tests: Wie einfach kann ich die Tests ausführen? Gibt es überhaupt Tests?
• Blick in Bug-Tickets: Führen neue Funktionen regelmäßig zu neuen Bugs? Wie werden sie angegangen?
• Blick in Releases: Wie wird das Projekt bereitgestellt? Gibt es Continuous Integration (CI) oder Continuous Deployment (CD)?
• Blick in die Kommunikation: Software zu bauen dreht sich um Kommunikation. Wie kommuniziert das Team? Gibt es ein Entscheidungsprotokoll? Wie funktionieren Pull Requests?
• Statische Analyse-Tools: Produkte wie SonarQube können helfen, dich zu führen und die Qualität eines Projekts zu bewerten.
• KI-Prompting: Du kannst Copilot bitten, zusammenzufassen, was eine Datei tut, und Verbesserungen vorzuschlagen. Siehe deren Dokumentation für Beispiele.

Software bleibt ein herausforderndes, aber spannendes Geschäft. Es ist schnelllebig, was bedeutet, dass wir oft zwischen Kontexten wechseln müssen. Wir hoffen, dass du eine neue Strategie gelernt hast, die dir hilft, mit etwas mehr Selbstvertrauen in deine nächste Codebasis einzutauchen.

Übrigens, wir nutzen auch cal.com! Wenn das, was wir anbieten, für dich interessant klingt, vereinbare gerne einen Termin mit uns: https://cal.com/team/peerigon/hello 👋

🤖 Erklärung zur Nutzung von KI in diesem Artikel: Dieser Artikel wurde von Menschen geschrieben (danke für das Feedback Irena und Julia!), einschließlich des Titels, der Konzepte und der Codebeispiele. Allerdings haben wir KI verwendet, um den Schreibstil zu verbessern.

Foto von Linh Ha auf Unsplash