Meilleures pratiques pour la transmission du code hérité

Dans quelques mois, un collègue passera à un nouveau projet et je vais hériter de l'un de ses projets. Pour me préparer, j'ai déjà commandé le logiciel Travailler efficacement avec Legacy Code de Michael Feathers .

Mais ces livres, ainsi que la plupart des questions sur le code existant que j'ai trouvées jusqu'à présent, concernent le cas de l'héritage du code tel quel. Mais dans ce cas, j'ai effectivement accès au développeur d'origine et nous avons un peu de temps pour une passation méthodique.

Quelques informations sur le morceau de code dont je vais hériter:

• Cela fonctionne: il n’ya pas de bugs connus, mais à mesure que les exigences de performances ne cessent d’augmenter, certaines optimisations deviendront nécessaires dans un avenir pas trop éloigné.
• Non documenté: Il n'y a pratiquement aucune documentation au niveau de la méthode et de la classe. Ce que le code est censé faire à un niveau supérieur, cependant, est bien compris, car j'écris depuis des années contre son API (en tant que boîte noire).
• Seuls les tests d'intégration de niveau supérieur: seuls des tests d'intégration testent l'interaction correcte avec d'autres composants via l'API (encore une fois, la boîte noire).
• Niveau très bas, optimisé pour la vitesse: ce code étant au cœur de tout un système d’applications, il a été optimisé à plusieurs reprises au fil des années et est de niveau extrêmement bas (une partie possède son propre gestionnaire de mémoire pour certaines structures). / enregistrements).
• Concurrent et sans verrouillage: Bien que je sois très familiarisé avec la programmation simultanée et sans verrouillage et que j'ai en fait contribué à quelques éléments de ce code, cela ajoute une couche de complexité supplémentaire.
• Large base de code: Ce projet particulier comporte plus de dix mille lignes de code, il est donc impossible que tout me soit expliqué.
• Écrit à Delphes: Je vais simplement exposer ceci, bien que je ne pense pas que le langage soit pertinent pour la question, car je pense que ce type de problème est agnostique.

Je me demandais quelle serait la meilleure utilisation de son temps jusqu'à son départ. Voici quelques idées:

• Tout construire sur ma machine: Même si tout doit être contrôlé dans le contrôle de code source, celui qui n’a pas oublié de vérifier un fichier de temps en temps, c’est donc probablement le premier ordre du jour.
• Davantage de tests: bien que je veuille davantage de tests unitaires au niveau de la classe afin de pouvoir détecter les bogues que je pourrais introduire très tôt, le code tel qu’il est actuellement n’est pas testable (classes énormes, méthodes longues, trop dépendances mutuelles).
• Ce qu'il faut documenter: Je pense que pour commencer, il serait préférable de centrer la documentation sur les zones du code qui seraient autrement difficiles à comprendre, par exemple en raison de leur nature de bas niveau / hautement optimisée. J'ai bien peur qu'il y ait quelques éléments qui pourraient paraître laids et qui auraient besoin d'être refactorisés / réécrits, mais il s'agit en réalité d'optimisations qui ont été publiées pour une bonne raison qui pourrait me manquer (cf. Joel Spolsky, Things You Should Ne fais jamais, partie I )
• Comment documenter: Je pense que certains diagrammes de classes de l'architecture et des diagrammes de séquence de fonctions critiques accompagnés de prose seraient les meilleurs.
• Qui documenter: Je me demandais ce qui serait mieux, de lui demander de rédiger la documentation ou de me l'expliquer, afin que je puisse rédiger la documentation. J'ai bien peur que des choses évidentes pour lui mais pas moi ne soient autrement pas couvertes correctement.
• Refactoriser à l'aide de la programmation par paire: cela pourrait ne pas être possible à cause des contraintes de temps, mais je pourrais peut-être refactoriser une partie de son code pour le rendre plus facile à maintenir pendant qu'il était encore là pour expliquer pourquoi les choses sont comme elles.

S'il vous plaît commenter et ajouter à cela. Puisqu'il n'y a pas assez de temps pour tout faire, je suis particulièrement intéressé par la définition de vos priorités.

Mise à jour: Une fois le projet de transfert terminé, j'ai développé cette liste avec mes propres expériences dans la réponse ci-dessous .

Comme vous avez accès au développeur, votre code demande: -

• Quels modules ont été les plus difficiles à coder / implémenter? Quels étaient les problèmes et comment ont-ils été surmontés?

• Quels modules ont généré le plus de bugs.

• Quels modules ont abouti aux bugs les plus difficiles à résoudre.

• Quels sont les morceaux de code dont il est le plus fier?

• Quels morceaux de code il aimerait vraiment refactoriser, mais, n’a pas eu le temps.

Ces questions vous donneront un aperçu de ce qui vous causera le plus de problèmes et, peut-être plus important encore, un aperçu des processus de pensée et des perspectives du développeur original.

Le projet de passation des pouvoirs étant terminé, je pense que je prendrais le temps de rédiger ma propre réponse contenant les éléments qui me convenaient le mieux.

• Obtenez tout sous contrôle de version: Après m'être assuré que tout ce que j'avais besoin de construire était sous contrôle de version, j'ai également cherché sur le disque dur de l'ancien développeur, à la recherche de scripts ou d'utilitaires supplémentaires qui seraient utiles pour déployer et / ou tester l'application pas enregistré.
• De haut en bas: je commencerais par un tour d'horizon des grandes classes et par une visite guidée avec l'ancien développeur des zones principales. Ensuite, je creuserais le reste par moi-même, en signalant des choses qui n’avaient aucun sens pour moi avec des //TODOmarqueurs.
• Rédigez toute la documentation moi-même: pendant que l'ancien développeur examinait mon écriture pour m'assurer de bien faire les choses, j'ai insisté pour tout écrire moi-même. De cette façon, je serais sûr que l'écriture avait du sens pour moi et pas seulement pour l'ancien développeur.
• Commentaires partout: j'ai ajouté des résumés de documentation XML à chaque classe et chaque méthode. De cette façon, je me suis assuré que j'avais au moins examiné chaque morceau de code et que j'avais suffisamment de compréhension pour résumer ce qu'il faisait dans une phrase. Cela facilitait également la compréhension des méthodes utilisant les méthodes / classes de synthèse en permettant à IntelliSense de collecter ces informations. Je pouvais aussi facilement identifier les zones du code que je devais encore examiner.
• Document proche de la source: Afin de faciliter la connexion entre le code source et la documentation, j'ai mis l'essentiel de ma documentation dans le code source. Pour la documentation de haut niveau décrivant l'interaction entre divers sous-systèmes, j'ai utilisé un wiki, car placer ces informations à un seul endroit du code ne fonctionnait pas. Toute la documentation doit être électronique et consultable en texte intégral.
• Diagrammes: Pour un aperçu de base, j'ai utilisé des diagrammes de classes de différentes granularités pour les différents sous-systèmes. Pour les parties concurrentes, les diagrammes d'objet et d'interaction ont été très utiles. voir aussi mon autre question sur le sujet .
• Refactoring en tant que paire: bien que j’ai refait le refactoring avec l’ancien développeur pour avoir une idée du code et rendre les choses plus faciles à maintenir, c’était un processus long et risqué, en raison du manque de bons outils de refactoring et de nombreux outils malveillants. dépendances entre les différentes parties. Le travail efficace de Michael Feathers avec Legacy Code est une aide précieuse, bien que le refactoring sans support d’outil approprié reste douloureux. Pendant la refactorisation, je lui laissais le contrôle de la souris et du clavier, car c'était plus amusant pour lui (voir aussi ma dernière puce) et j'étais libre d'écrire ce que j'apprenais.
• Archivages séparés pour les commentaires et les modifications: après avoir introduit un bogue par inadvertance en écrivant un commentaire sur un bogue override, j'ai pris soin de faire des commentaires et des modifications dans des enregistrements séparés. J'ai utilisé un petit utilitaire pour supprimer tous les commentaires du code source avant d’archiver quelque chose, donc un diff d’un enregistrement avec commentaire seul montrerait 0 différence. Toutes les modifications (par exemple, la suppression de champs non utilisés) ont été soigneusement examinées par l'ancien développeur pour s'assurer que je ne supprimais pas les éléments qui étaient encore nécessaires.
• Procédure pas à pas ligne par ligne des passages critiques: Pour les passages optimisés / complexes, je lisais le code ligne par ligne avec l'ancien développeur et parfois même avec un troisième collègue. De cette façon, j'ai bien compris le code et, à mesure que de plus en plus de personnes contrôlaient le code, nous avons en fait identifié quelques bugs ainsi que des éléments pouvant être optimisés.
• Soyez rapide et gardez l'ancien développeur motivé: j'ai remarqué que l'ancien développeur était de moins en moins intéressé car son dernier jour se rapprochait (sans surprise). Je veillerais donc à ce que les parties les plus critiques soient remises en premier, laissant le reste à moi-même, le cas échéant. J'ai aussi essayé de lui laisser les choses les plus amusantes (par exemple, le contrôle du clavier lors de la programmation en binôme) et de faire des choses ennuyeuses comme écrire de la documentation par moi-même.
• Identifier les demandes de fonctionnalités: j'ai trouvé utile de demander à l'ancien développeur une liste des fonctionnalités que les utilisateurs avaient demandées mais qui n'avaient pas encore été ajoutées. Il y avait quelques petites choses qui, pour moi, semblaient simples à ajouter, mais pour lesquelles il y avait une bonne raison de ne pas les ajouter, car elles auraient brisé d'autres choses lors de leur mise en œuvre, comme je l'avais pensé au début.

Ayant été dans une situation similaire, j'estime que les éléments suivants mériteraient également d'être pris en compte:

• Assurez-vous de pouvoir effectuer et tester un déploiement: Faites votre propre déploiement du produit, en partant de zéro - et vérifiez qu'il est identique à celui effectué par la personne qui part. Cela garantirait que les scripts et les instructions soient clairs pour vous, et éviterait tout oubli accidentel, tel que des ingrédients n'ayant pas été enregistrés dans votre système de contrôle de version. (Je ne dis pas que cela se produirait, mais que si cela se produisait, ce serait beaucoup plus facile à gérer maintenant, avant le départ de la personne)

  (Cela peut ne pas être pertinent pour vous, par exemple si vous effectuez déjà une intégration continue ou un déploiement continu, mais cela vaut la peine d'être mentionné, juste au cas où ...)

• Écrire davantage de tests: C’est un très bon moyen de tester votre compréhension d’un système. Cela vous permettra (ou vous forcera) à regarder de plus près les zones du code, et confirmera soit que le code est aussi exempt d'erreurs que vous soupçonnez, soit révélera les zones où vous pensiez avoir compris l'intention, mais en réalité vous besoin de demander des précisions à votre collègue avant son départ

• Écrire par paires de la documentation: il s’agit d’un moyen efficace d’écrire des aperçus. Je suggère que vous obtenez votre collègue pour décrire une fonction ou d'une zone, puis vous écrire vers le haut, dans la documentation, dans vos propres mots. Nous avons trouvé que cela était massivement plus facile quand cela était fait par deux personnes ensemble.

Je donnerais personnellement la priorité à la rédaction des tests par rapport à la rédaction de la documentation, car ils vous permettront probablement de mieux comprendre - ou d’être plus ferme.

En ce qui concerne le refactoring utilisant la programmation en paire , la seule chose que je dirais, c'est que cela risque de devenir un gouffre sans fond, d'autant plus que vous avez dit que vous n'aviez que des tests de haut niveau. Vous constaterez peut-être que cela finit par utiliser beaucoup plus de temps que prévu.

+1 pour les réponses que vous avez déjà dans votre question!

Visite guidée
10 000 lignes de code, c'est beaucoup, mais je pense qu'il n'est toujours pas impossible de demander à l'autre type de vous donner une «visite guidée». Vous vous asseyez ensemble devant le code et il vous emmène dans un voyage de haut en bas, en descendant les "couches". Vous auriez besoin de le faire en petites rafales - tout d'un coup vous tuerait tous les deux.

Zoom-in, zoom-out
L'avantage de faire ceci est que pendant qu'il vous l'explique, il aura presque certainement des moments "oh, oui, il y a aussi ceci" qu'il n'aurait peut-être pas s'il essayait juste de le documenter tout seul. Et vos questions vous aideront à vous concentrer sur les éléments évidents pour lui, mais pour personne d'autre. Ce type d'interaction zoom avant / arrière n'est possible que face à face. Il est difficile d'essayer d'écrire ou de lire quelque chose comme ça.

Documentation
Je pense que vous devriez documenter de manière indépendante - il doit commencer par le bas (au cas où vous n'auriez pas le temps de le faire ensemble), et vous devriez commencer par le haut, sur la base de ce que vous avez compris. sa visite guidée et comme s’il s’agissait d’une autre personne [lors d’un emploi précédent, j’ai hérité d’une charge de code "hérité" et je n’avais que le temps de la documenter avant de partir moi-même :)].

Où est quoi?
Le but de la plupart de cela est que vous puissiez avoir une idée de l'endroit où les choses se passent. Donc, étant donné un bug ou une modification particulière, vous pouvez très rapidement trouver la place dans le code sur laquelle vous devez vous concentrer. Vous pouvez vous tester en prenant la liste des vieux bugs et en vérifiant si vous pouvez prédire avec précision où se situe le problème.

Faites-le sécher.
Peu importe s'il finit par vous détester (sourire), votre travail consiste à obtenir le plus d'informations possible du cerveau de ce type dans la mesure du possible. Assurez-vous que la gestion est de votre côté et qu'ils accordent la priorité au transfert de connaissances plutôt que de "réparer ces derniers bogues avant qu'il ne parte" (à moins que vous ne les répariez ensemble ...).

Je suggère ce qui suit (en plus de ce qui est déjà identifié) - Premièrement, demandez à votre responsable de vous donner le temps de travailler avec ce gars autant que possible et essayez de vous asseoir avec lui chaque fois qu'il est chargé de faire un changement. Vous n'avez pas besoin de savoir tout ce qu'il fait, mais d'essayer d'attraper autant que vous le pouvez. Le plus important être amis avec lui.

Traitez le transfert comme un projet, mettez en place un plan et impliquez la direction.

0 - Assurez-vous de savoir utiliser le système.

1 - Faites un inventaire clair des composants de la solution, de leur source et de leur emplacement (dans différents référentiels)

2 - Obtenez et, si possible, gérez les mots de passe des différents serveurs à partir de maintenant. Assurez-vous d'avoir toutes les informations du compte administrateur

3 - Obtenez les licences de chaque composant externe sauf si cela sort de votre portée (par exemple, des DLL spéciales, une base de données, etc.)

4 - Obtenez un rapport écrit sur l’état actuel du système du développeur et de vos clients (s’ils sont locaux de votre entreprise)

5 - Obtenez la documentation pour les règles de gestion, les formules de calcul, etc. Vous pouvez le faire avec lui. Demandez-lui des courriels, des informations sur les réunions, des documents relatifs aux besoins des utilisateurs, des documents de conception, etc., qui vous seront fournis.

6 - Obtenir une liste des événements planifiés (exécutions mensuelles, hebdomadaires) auxquels le logiciel doit répondre

7 - Apprenez les procédures de sauvegarde / restauration

8 - Comprendre le ou les frameworks utilisés dans la construction de l'application

9 - Informez-vous des modifications demandées / attendues / prévues et de l'état de toutes les demandes utilisateur en attente. Commencez à essayer de déterminer comment faire cela vous-même.

10 - Assurez-vous que vos environnements de test et de développement sont très similaires.

11 - Essayez d'identifier les dépendances majeures (sur d'autres systèmes ou entre composants) qui ne peuvent pas être facilement repérées.

12 - Identifier et documenter les versions requises de chaque utilisation du logiciel et son contact fournisseur (si nécessaire)

13 - Identifiez tous les outils spéciaux qu'il n'utilisait pas, au cas où cela pourrait vous aider.

14 - Obtenez un flux de système de haut niveau. et commencez à construire votre bibliothèque de documentation

15 - Comprendre comment gérer la sécurité des utilisateurs pour l'application

16 - Obtenez le journal des bogues et essayez de comprendre les actions et comment l'action a affecté les anciennes données (le cas échéant)

17 - Connaissez les processus qui prennent trop de temps et que devez-vous surveiller (par exemple, des tailles de fichier inhabituelles, des fichiers en double, etc.) le cas échéant.

18 - Vérifier l'horloge du serveur de production

19 - Identifiez l'emplacement des configurations et comparez chaque configuration d'environnement avec la production pour savoir quels paramètres sont différents et pourquoi

20 - Obtenir les coordonnées de ce type

21 - Si le système est interne, planifiez une réunion avec les utilisateurs du système (vous devez savoir qui ils sont et quel est le rôle qu'ils jouent) et leur présenter. Écoutez ce qu'ils ont à dire sur le système et sur leurs éventuels problèmes. Assurez-vous d'être inclus dans les courriels le plus tôt possible (après l'approbation de votre responsable).

22 - Évaluez votre compréhension une semaine avant son départ et signalez tout problème que vous considérez comme un risque.

Puisque vous avez mentionné que vous n'aviez pas de base de données, cette liste a été raccourcie.

Bonne chance.

Je considérerais d’abord les pièces les plus compliquées, optimisées pour les performances. Je lui demanderais d’abord de documenter ces parties et de vous les expliquer une à la fois, puis d’essayer d’écrire des tests sur ces parties (avant et après les tests de performance, afin que vous puissiez voir si une nouvelle optimisation améliore les choses, voire s’aggrave). ) et demandez à l'autre personne de passer les tests en revue. De cette façon, il documente et explique, vous utilisez l'explication pour écrire des tests (pendant qu'il documente un domaine différent), et son compte rendu vous aidera à vous assurer que vous avez bien compris ce que vous devriez être en train de tester. De cette façon, vous obtenez également des ressources de test supplémentaires pour certaines des parties les plus critiques de l'application et la documentation des optimisations de performances spécialisées.

S'il reste du temps, je passerais ensuite à un processus similaire avec les parties de la demande qui ont le plus souvent besoin de modifications au fil des ans, mais qui ne font pas partie du premier groupe d'éléments documentés.

Puis documentez tout ce qui reste.

Je pense que la meilleure façon de concevoir un code volumineux est une approche descendante. Essayez d'abord de comprendre la situation dans son ensemble, puis approfondissez progressivement les composants un à un.

Maintenant, à chaque niveau de creusage, demandez-lui de hiérarchiser les parties qui nécessitent le plus d'attention. Demandez-lui de vous expliquer autant que possible, mais toujours le documenter vous-même.

La meilleure partie de la documentation vous-même est que lorsque vous reviendrez plus tard, vous n'aurez aucun problème à vous rappeler le même état cognitif que celui dans lequel vous vous trouviez, lorsqu'il vous l'a expliqué. Vous pouvez comprendre beaucoup plus facilement ce que vous avez écrit que ce que quelqu'un d'autre a fait. D'après mon expérience, deux personnes documentant le même morceau de code ne produisent pas de texte similaire.

Ceci, je suppose, résoudra également vos problèmes de "quoi et comment documenter". Quand il vous explique tout, vous pouvez alors décider vous-même de ce que vous souhaitez documenter lorsque vous revenez au code - et documenter uniquement ces parties.

L’idée est d’abord de bien comprendre le code (en sa présence), puis d’écrire / faire tout ce qui vous permettra de le reprendre plus tard (en son absence).

En comprenant parfaitement le code, je veux dire que vous devez avoir une idée de la situation dans son ensemble - et du lien qui existe entre chaque élément et cette image dans son ensemble. J'ai trouvé particulièrement utile de savoir comment chaque pièce constitue le tout. N'essayez pas de comprendre quoi que ce soit de manière isolée - ne perdez jamais de vue son contexte.

Enfin, une fois que vous avez fait ce qui précède, prenez le contrôle de manière proactive. Décidez vous-même pour quels éléments vous avez besoin d'une couverture par test unitaire. quelles parties doivent être (ou peuvent être) optimisées, comment peut-on restructurer un composant, etc. Sachez que si vous connaissez le système, vous pouvez prendre toutes les décisions une fois qu'il est parti.

Je compatis.

Quelques suggestions:

1. Enregistrez chaque conversation que vous avez avec le programmeur sortant!
2. Demandez la motivation derrière les "gros" problèmes. C'est bien que vous compreniez l'API, mais cherchez les décisions internes - pourquoi le code a-t-il été partitionné tel quel? quelles sont les responsabilités.
3. Faites un effort pour vraiment étudier le code. Lorsque vous prenez en charge les tâches de maintenance et de support, vous devez parfois "étudier le code tout en progressant". Résistez si vous le pouvez et étudiez vraiment le code.
4. Rechercher des scénarios. Vous connaissez l'API - voyez comment le code se comporte. Un exemple qui me vient à l’esprit est celui d’un module Fax. En tant qu'utilisateur de l'API, vous devez préparer une image de page et envoyer au code une commande pour transmettre la page. Demandez au programmeur sortant de tracer avec vous le code pour voir comment ce scénario se déroulera. Ensuite, bien sûr, choisissez le scénario "page de réception".
5. 80/20 - essayez d'abord de couvrir les scénarios les plus courants.
6. Considérons une réécriture. Si le code est ancien et que les interfaces sont bien définies, la technologie a peut-être suffisamment changé pour le justifier.
7. Je déteste dire ça, mais songez à chercher un nouvel emploi.

Si vous voulez une documentation correcte, achetez une copie de Pascal Analyzer (PAL) de manière raisonnablement simple . Je l’ai utilisée pour des projets Delphi et c’était génial: ils ont peut-être maintenant divisé la fonctionnalité de documentation en un produit que je ne connais pas bien (Navigateur Pascal) vous devrez donc peut-être acheter les deux (<300 USD), mais PAL était un excellent outil pour comprendre où les variables étaient utilisées, où les fonctions étaient appelées, etc. et détectant toutes sortes de problèmes potentiels avec le code.

Utilisez PAL pour avoir une idée de la structure du code, ainsi qu’une liste d’environ 1 000 améliorations suggérées, si mon expérience en était la cause. Travailler à travers la liste va améliorer la qualité du code, le simplifier grandement et vous rendre la vie plus facile pour l'avenir. Delphi lui-même prend en charge le refactoring dans les versions récentes (les 5 dernières années environ). Vous devez inclure tout dans le fichier dpr pour que cela fonctionne vraiment lorsque je le faisais, alors gardez cela à l'esprit.

Si vous voulez des tests unitaires, téléchargez DUnit et commencez à créer des tests avec le codeur d'origine - c'est probablement une façon constructive d'utiliser au moins une partie de leur temps.

Bien que vous n’ayez pas mentionné de base de données backend, mais en supposant qu’il en existe une, vous devriez

1. Obtenez le modèle de données documenté en particulier les colonnes et PK-FK
2. Configurez une trace SQL et enregistrez toutes les requêtes qui sont déclenchées lors de l'utilisation de l'application. L'ordre d'exécution des requêtes vous donnera une bonne idée du déroulement de l'application et vous aidera également au débogage.

Je suis dans la même situation où notre architecte a déménagé en Australie et a laissé beaucoup d'héritage, comme il était avec l'entreprise au cours des 8 dernières années. Il a lui-même hérité des documents de l'ancien architecte, un entrepreneur.

Vous et d'autres avez déjà mentionné des points positifs, mais voici les problèmes auxquels nous avons été confrontés après son départ, vous pourriez vous préparer mieux ...

1) (Personne technique) Coordonnées des clients avec lesquels il traite.

2) Son compte sous lequel il a acheté des licences de logiciels, des clés qui doivent être renouvelées chaque année et des processus / coûts pour les renouveler.

3) Document de configuration des bibliothèques / composants logiciels tiers et des produits s’intégrant à vos produits. Nous avons lutté pendant 4 jours pour ramener une machine qui avait été perdue à cause d'un espace informatique réduit et d'une instruction erronée qui leur avait été transmise.

4) Documents / étapes utilisés pour déposer le code source sur des logiciels. Sociétés de dépôt, par exemple Escrow.

5) La liste est encore longue mais peut ne pas s'appliquer à vous également Aucune quantité de documentation ne peut remplacer une personne réelle, alors gardez ses détails à portée de main, restez en bons termes et bonne chance :)

Aussi je ne sais pas si c'est la première fois pour vous. Pour moi, j'ai travaillé avec 5/6 employeurs et j'ai toujours hérité du code avec une mauvaise documentation ou aucune documentation. Donc, avec toute la documentation, restez positif :)