So arbeiten Sie an einer unbekannten Codebasis

In unserem Beruf ist es üblich, mit einer unbekannten Codebasis zu arbeiten. Es passiert jedes Mal, wenn man einem neuen Projekt beitritt oder bei großen Projekten sogar an einem bisher unberührten Teil arbeiten muss.

Dieses Vorkommnis ist nicht darauf beschränkt, dass ein Entwickler einen Fehler beheben muss; Das kann ein Lösungsarchitekt sein, der ein neues Feature entwerfen muss, oder ein OpenSource-Mitwirkender, der in seiner Freizeit an einem GitHub-Problem arbeitet. Daher möchte ich beschreiben, wie ich an die Situation herangehe, damit sie anderen zugute kommt.

Ein Beispielproblem

Um meinen Standpunkt zu veranschaulichen, verwende ich ein häufiges GitHub-Problem, bei dem eine neue Funktion für ein Open-Source-Projekt angefordert wird.

Während meiner Arbeit für Hazelcast habe ich regelmäßig die sogenannten „guten ersten Ausgaben“ gescannt, um sie bei Hackathons zu bearbeiten. Ich könnte nie einen solchen Hackathon leiten, aber das ist nebensächlich. Meine Idee war es, Menschen, die daran interessiert sind, zu Open Source beizutragen, dabei zu helfen, sich mit der Codebasis vertraut zu machen.

Damals fand ich dieses interessante Problem:

Unterstützung für getQuiet-Vorgang hinzufügen http://ehcache.org/apidocs/net/sf/ehcache/Cache.html#getQuiet(java.lang.Object) ?

Die Idee besteht darin, einen Eintrag abzurufen, ohne ihn zu berühren, was bedeutet, dass der Zeitstempel des letzten Zugriffs nicht aktualisiert wird.

Der Anwendungsfall dahinter besteht darin, die Existenz eines Schlüssels überwachen zu können, ohne die Entfernung dieses Schlüssels zu ändern.

-- Verteilte Karte: Unterstützung für den getQuiet-Vorgang hinzugefügt

Wie würde ich als OpenSource-Mitwirkender an die Arbeit herangehen?

Diagrammerstellung ist der Schlüssel

Die Dokumentation ist der erste Schritt, um ein neues Projekt in Angriff zu nehmen. Bei einem regulären Projekt wird die Dokumentation wahrscheinlich fehlen, unvollständig oder teilweise (wenn nicht vollständig) irreführend sein; Bei einem Hackathon ist die Zeit möglicherweise zu knapp, um es im Detail zu lesen.

Erfolgreiche Open-Source-Projekte verfügen im Allgemeinen über eine gute Dokumentation. Die Dokumentation richtet sich jedoch hauptsächlich an Benutzer, selten an Entwickler. Selbst wenn dies der Fall ist, ist die Wahrscheinlichkeit gering, dass das Problem in der Dokumentation behoben wird.

Aus diesem Grund besteht mein Einstiegspunkt darin, ein Diagramm zu zeichnen. Beachten Sie, dass einige Tools zwar Code zurückentwickeln und automatisch Diagramme zeichnen können, ich sie jedoch nicht absichtlich verwende. Das manuelle Zeichnen eines Diagramms hat gegenüber einem automatisch generierten Diagramm viele Vorteile:

• Es konzentriert sich auf Bereiche des Kodex, die für das jeweilige Problem relevant sind.

• Es zwingt den Zeichner, den Code zu lesen und zu verstehen, der die einzige Quelle der Wahrheit darstellt.

• Es baut unser mentales Modell des Codes auf.

• Es dokumentiert unsere Ergebnisse, um später zugänglich zu sein. Beachten Sie jedoch, dass der Dokumentationswert mit der Zeit abnimmt, da sich der zugrunde liegende Code weiterentwickelt und sich beide Wege trennen.

Lassen Sie uns ein Diagramm für den Code für das Problem erstellen. Zuerst werden wir das Repo lokal klonen, um es in unserer Lieblings-IDE zu öffnen; Die einzige erforderliche Funktion besteht darin, dass man beim Klicken auf einen Methodenaufruf zur Methode weitergeleitet wird.

Was das Diagramm selbst betrifft, nennen Sie mich altmodisch, aber ich bevorzuge immer noch UML-Sequenzdiagramme aus zwei Gründen:

• Ich habe einige Erfahrung mit ihnen.

• Semantik ist kein Ad-hoc- Konzept, sondern wird bis zu einem gewissen Grad von Leuten geteilt, die sich mit UML auskennen.

Ohne weitere Umschweife, hier ist es:

Nachdem wir das Diagramm gezeichnet haben, können wir ziemlich schnell feststellen, wo das Problem liegt:

 public abstract class AbstractCacheRecordStore<R extends CacheRecord, CRM extends SampleableCacheRecordMap<Data, R>> implements ICacheRecordStore, EvictionListener<Data, R> { protected long onRecordAccess(Data key, R record, ExpiryPolicy expiryPolicy, long now) { record.setAccessTime(now); // 1 record.incrementAccessHit(); return updateAccessDuration(key, record, expiryPolicy, now); } //... }

1. Der DefaultRecordStore liest den Record , was die Aktualisierung der letzten Zugriffszeit auslöst.

Die Behebung des Problems liegt außerhalb des Rahmens dieses Beitrags. Um die beste Lösung zu entwickeln, müssen wir mit Personen sprechen, die mit dem Gesamtdesign besser vertraut sind. Ein guter Ansatz bei einem Hackathon besteht darin, zunächst mindestens zwei Alternativen anzubieten und deren jeweilige Kompromisse zu dokumentieren.

Für die Werkzeugausstattung stehen zahlreiche Alternativen zur Verfügung. Meine Präferenzen gehen zu PlantUML :

• Es bietet eine Web-App und einen Docker-Container
• Es generiert SVG- oder PNG-Bilder
• Es ist hautbar
• Es ist Open Source und kostenlos
• Es wird regelmäßig gewartet

Abschluss

Das Verstehen einer vorhandenen Codebasis ist unabhängig von der genauen technischen Rolle einer Person eine entscheidende Fähigkeit. Die Erstellung eines Diagramms trägt wesentlich dazu bei, dieses Ziel zu erreichen, und bietet darüber hinaus den Vorteil einer Dokumentation.

Ich mag UML-Diagramme, weil ich mit ihnen vertraut bin und sie eine gemeinsame Semantik bieten.

Wenn Sie also eine Codebasis besser verstehen möchten, müssen Sie mehr als nur ihren Code lesen; Sie müssen Diagramme zeichnen.

Ursprünglich veröffentlicht bei A Java Geek am 14. Mai 2023