Comment travailler sur une base de code inconnue

Dans notre métier, il est courant de travailler sur une base de code peu familière. Cela se produit à chaque fois que l'on rejoint un nouveau projet ou même que l'on a besoin de travailler sur une partie auparavant intacte dans les grands.

Cette occurrence n'est pas limitée à un développeur devant corriger un bogue ; il peut s'agir d'un architecte de solution devant concevoir une nouvelle fonctionnalité ou d'un contributeur OpenSource travaillant sur un problème GitHub pendant son temps libre. Par conséquent, je veux décrire comment j'aborde la situation afin qu'elle puisse profiter aux autres.

Un exemple de problème

Pour illustrer mon propos, j'utiliserai un problème GitHub courant demandant une nouvelle fonctionnalité sur un projet Open Source.

En travaillant pour Hazelcast, je scannais régulièrement les soi-disant "bons premiers numéros" pour travailler lors de hackathons. Je n'ai jamais pu organiser un tel hackathon, mais ce n'est pas la question. Mon idée était d'aider les personnes intéressées à contribuer à l'Open Source à se familiariser avec la base de code.

A l'époque, j'avais trouvé ce problème intéressant :

Ajout de la prise en charge de l'opération getQuiet http://ehcache.org/apidocs/net/sf/ehcache/Cache.html#getQuiet(java.lang.Object) ?

L'idée est de pouvoir obtenir une entrée sans la toucher, ce qui signifie qu'elle ne mettra pas à jour le dernier horodatage consulté.

Le cas d'utilisation derrière cela est de pouvoir surveiller l'existence d'une clé sans changer l'éviction de cette clé.

-- Carte distribuée : ajout de la prise en charge de l'opération getQuiet

En tant que contributeur OpenSource, comment aborderais-je le travail ?

La création de diagrammes est la clé

La documentation est la première étape pour se lancer dans un nouveau projet. Sur un projet régulier, la documentation sera probablement manquante, incomplète ou partiellement (sinon entièrement) trompeuse ; lors d'un hackathon, le temps peut être trop court pour le lire en détail.

Les projets Open Source réussis ont une bonne documentation en général. Cependant, la documentation est principalement orientée vers les utilisateurs, rarement vers les développeurs. Même lorsque c'est le cas, les chances que la documentation résolve le problème sont faibles.

Pour cette raison, mon point d'entrée est de dessiner un diagramme. Notez que même si certains outils peuvent désosser le code et dessiner des diagrammes automatiquement, je ne les utilise pas exprès. Dessiner un diagramme manuellement présente de nombreux avantages par rapport à un diagramme généré automatiquement :

• Il se concentre sur les domaines du code pertinents pour le problème en question.

• Il oblige le dessinateur à lire et à comprendre le code, qui est la seule source de vérité.

• Il construit notre modèle mental du code.

• Il documente nos découvertes pour être accessible plus tard. Cependant, notez que la valeur de la documentation diminue avec le temps à mesure que le code sous-jacent évolue et les deux se séparent.

Créons un diagramme pour le code du problème. Tout d'abord, nous allons cloner le référentiel localement pour l'ouvrir dans notre IDE préféré ; la seule fonctionnalité requise est que lorsque l'on clique sur un appel de méthode, on est dirigé vers la méthode.

Pour le diagramme lui-même, appelez-moi démodé, mais je préfère toujours les diagrammes de séquence UML pour deux raisons :

• J'ai une certaine expérience avec eux.

• La sémantique n'est pas ad hoc mais partagée entre les personnes qui connaissent UML, jusqu'à un certain point.

Sans plus tarder, voilà:

Après avoir dessiné le diagramme, nous pouvons localiser assez rapidement où se situe le problème :

 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. Le DefaultRecordStore lit le Record , ce qui déclenche la mise à jour de la dernière heure d'accès.

La résolution du problème sort du cadre de cet article. Cela implique de parler à des personnes plus familières avec la conception globale pour développer la meilleure solution. Une bonne approche dans un hackathon est d'abord de proposer au moins deux alternatives et de documenter leurs compromis respectifs.

Pour l'outillage, de nombreuses alternatives sont disponibles. Mes préférences vont à PlantUML :

• Il propose une application web et un conteneur Docker
• Il génère des images SVG ou PNG
• C'est skinnable
• C'est Open Source et gratuit
• Il est entretenu régulièrement

Conclusion

Comprendre une base de code existante est une compétence cruciale, quel que soit son rôle technique exact. La création d'un diagramme contribue grandement à cet objectif, avec l'avantage supplémentaire de la documentation.

J'aime les diagrammes UML parce que je les connais et qu'ils offrent une sémantique partagée.

Par conséquent, si vous voulez mieux comprendre une base de code, vous avez besoin de plus que simplement lire son code ; vous devez dessiner des diagrammes.

Publié à l'origine sur A Java Geek le 14 mai 2023