Comment introduire du code à un collègue

Comment allez-vous présenter la base de code, qui peut être assez complexe et emmêlée avec beaucoup de "pièges", à un nouveau membre de votre équipe?

Je pense que le moyen le plus simple serait de disposer de l'architecture globale avec des diagrammes et de prendre quelques semaines (ou mois) pour donner à la nouvelle personne des tâches bien définies (et bien définies) à mesure qu'elle s'habitue au code.

Cependant, en tant que consultant (et employé junior, je ne peux pas toujours avoir cela, soit en raison de contraintes de temps ou de désignations de rôles d'équipe. (J'ai été sur ce projet particulier deux fois plus longtemps que quiconque, donc "junior" n'est en aucun cas "en sait moins sur le code / projet.")

J'ai été chargé à plusieurs reprises maintenant de présenter un nouveau membre au projet et au code, et malheureusement, chaque fois que je trouve que je ne suis pas beaucoup mieux que le précédent. J'adore les diagrammes et les images, mais je pense souvent qu'ils ne tiennent pas suffisamment compte de la complexité d'un système. (Qu'en est-il de tous les "pièges" du petit?)

Le projet arrive à un point où nous allons le remettre au client, et pour rendre les choses plus difficiles, la personne avec qui je ferai un transfert de connaissances est essentiellement à la sortie du collège. (Pas que je sois beaucoup mieux quand je fais des transferts de connaissances avec des développeurs seniors.)

J'assiste à un groupe d'utilisateurs une fois par mois et à d'autres opportunités au fur et à mesure qu'elles se présentent.

Tout avis serait grandement apprécié. Je recherche surtout une ligne directrice que je peux suivre. Par exemple: par où commencer? Comment procédez-vous? Comment couvrez-vous des technologies ou des modèles inconnus de la part de l'auditeur sans prendre toute la journée? Où liez-vous la logique métier par rapport à la structure de code?

Je vous remercie!

(Comme toujours, n'hésitez pas à modifier la question comme bon vous semble.)

La première étape consiste bien sûr à supprimer les "accrochages" du code. Un code clair, concis et cohérent est plus facile à utiliser, à utiliser et à déboguer.

Par où commencer?

Je demande au nouveau venu comment il veut entrer dans la base de code. Tout le monde apprend différemment. Certaines personnes aiment avoir de petites tâches avec lesquelles travailler. Certains aiment déboguer le code existant. Certains veulent voir le code s'exécuter pour comprendre ce qu'il fait. Certains veulent commencer au point d'entrée et simplement naviguer. Certains veulent des diagrammes visio ... Aucun modèle d'ensemble ne fonctionnera mieux pour tout le monde.

Comment couvrez-vous des technologies ou des modèles inconnus de la part de l'auditeur sans prendre toute la journée?

Je les évite. Qu'ils soient des boîtes noires jusqu'à ce que le nouveau venu pose des questions à leur sujet. Ensuite, fournissez juste assez d'informations pour en avoir l'essentiel, avec l'indication qu'ils peuvent en savoir plus sur leur propre temps, ou demander plus tard quand les informations générales sont plus connues.

Où liez-vous la logique métier par rapport à la structure de code?

J'essaie de ne pas. Il est presque toujours préférable que le nouvel arrivant apprenne par lui-même afin qu'il s'inscrive dans son esprit dans une structure plus naturelle à sa façon de penser.

Une chose à retenir est de garder les instructions courtes. Les gens ont tendance à vérifier assez rapidement, donc toute instruction supplémentaire à ce stade ne «colle» pas. Montrez-leur les choses pendant 15 à 60 minutes (différentes personnes ont des durées d'attention différentes), puis faites une pause de 5 à 30 minutes pour qu'elles le traitent.

D'après mon expérience, un bon moyen de combler le fossé entre la large vue d'ensemble d'un diagramme d'architecture et les détails concrets de l'utilisation réelle du code consiste à effectuer une analyse descendante du système, c'est-à-dire ce qui se passe lorsqu'une demande arrive (pour le code serveur ) ou un utilisateur effectue une entrée (pour le code client), puis explique étape par étape toutes les couches de code impliquées.

Une autre façon est une "visite guidée" du code source, c'est-à-dire parcourir les packages / espaces de noms / modules / répertoires et expliquer ce que le code dans chacun d'eux fait en général. Bien sûr, cela nécessite que le code soit disposé de manière un peu logique.

Vous ne leur enseignez pas la base de code, vous leur enseignez votre travail. N'essayez pas de penser à ce dont ils pourraient avoir besoin, regardez ce que vous avez réellement besoin de savoir lorsque vous faites votre travail.

Consultez les derniers mois de l'historique du suivi des bogues, les histoires d'utilisateurs Scrum, les rapports d'état et les commits de contrôle de source. Quels fichiers avez-vous le plus touchés? Quel code est le plus problématique? Quelles tâches vous ont pris le plus de temps? Il y a de fortes chances que si vous n'y avez pas touché ces derniers mois, ce n'est pas aussi important que vous pourriez le penser.

Regardez la pile d'impressions sur votre bureau. Vérifiez l'historique récent de votre navigateur. Recherchez les e-mails enregistrés auxquels vous vous référez fréquemment, les contacts que vous utilisez, les documents que vous avez téléchargés. Certaines des références les plus utiles que j'ai transmises à d'autres sont les notes que j'ai gardées pour moi lors de mon premier apprentissage ou de la conception du système. Quel est le matériel de référence est le plus utile pour vous ?

Tirez ensuite votre arriéré connu. De quoi auriez-vous besoin pour effectuer des recherches afin de terminer ces tâches? Quels domaines de code contiennent probablement le problème? Transmettez cette information comme si vous preniez des notes pour vous-même.

Si vous faites référence à des graphiques ou des diagrammes dans votre travail quotidien, incluez-les. Si vous n'avez jamais pris la peine d'en créer un, cela ne sera probablement pas aussi utile à votre successeur / collègue.

L'une des tâches les plus difficiles à enseigner consiste à se mettre à sa place. Dans ce cas, vous êtes à leur place. Tirer le meilleur parti.

Le travail de support est le meilleur, prenez un bug facile et parcourez-les à travers les zones où il sera trouvé. ils apprendront rapidement comment le code s'assemble. Naturellement, ils viendront pour poser des questions sur ce bogue et la base de code, mais ils y arriveront (et vous obtiendrez un bogue corrigé). Souvent, il est beaucoup plus facile de comprendre les choses avec des exemples, de même, il est plus facile de travailler sur une base de code en la parcourant dans un débogueur.

Si vous n'êtes pas sûr des changements de code (ou ils le sont, je ne suis généralement pas sûr de mes corrections de code jusqu'à ce que je sois familier avec la base de code), vous pouvez le consulter avant de vous enregistrer.

Bien sûr, vos idées existantes de vues d'ensemble et de schémas fonctionnels sont des premières étapes essentielles.