Pause café #20. Qu'est-ce que le code existant et comment l'utiliser. Des outils qui facilitent la rédaction de la documentation technique

Qu'est-ce que le code existant et comment l'utiliser

Source : Dou Tôt et tard, un programmeur devra probablement rencontrer du code existant. Pour atténuer les conséquences de cette connaissance, j'ai sélectionné quelques conseils pratiques et exemples tirés de ma propre expérience - en particulier de l'utilisation d'un système Java existant.

Fonctionnalités héritées

L'héritage est le code de quelqu'un d'autre, qui est souvent si terrible qu'il n'est généralement pas clair comment l'utiliser. Et si vous devez travailler avec un système existant, en plus de l'ancien code, vous rencontrerez également :

• avec une technologie obsolète;
• architecture hétérogène;
• manque, voire absence totale, de documentation.

En fait, le code existant n’est pas si effrayant, et voici pourquoi : si le système a vécu toutes ces dix années et fonctionne toujours, alors il a une certaine utilité. Peut-être que cela rapporte beaucoup d'argent (contrairement à votre dernière startup). De plus, ce code serait relativement fiable s’il était capable de survivre en production aussi longtemps. Par conséquent, les modifications doivent être apportées avec prudence. Tout d’abord, vous devez comprendre deux choses :

1. Nous ne pouvons pas manquer de respect à un système qui rapporte des millions de dollars ou auquel des milliers de personnes ont accès chaque jour. Aussi mal écrit soit-il, ce code dégoûtant a survécu jusqu'à la production et fonctionne 24h/24 et 7j/7.

2. Étant donné que ce système rapporte de l’argent réel, travailler avec lui implique une grande responsabilité. Ce n'est pas une startup, mais quelque chose avec lequel les utilisateurs travailleront demain. Cela implique également un coût d’erreur très élevé, et il ne s’agit pas ici des réclamations du client, mais de la situation réelle.

Ingénierie inverse

Pour travailler avec succès avec du code existant, vous devrez utiliser des techniques d'ingénierie inverse. Tout d’abord, vous devez lire attentivement le code pour comprendre exactement comment il fonctionne. Ceci est obligatoire, car nous n'aurons probablement pas de documentation. Si nous ne comprenons pas le cheminement de pensée de l’auteur, nous apporterons des changements aux conséquences imprévisibles. Pour vous en protéger, vous devez également vous plonger dans le code adjacent. Et en même temps, bougez non seulement en largeur, mais aussi en profondeur. Où la méthode est-elle appelée avec l’erreur ? D'où vient le code qui l'appelle ? Dans un projet existant, la « hiérarchie des appels » et la « hiérarchie des types » sont utilisées plus souvent qu'autre chose. Vous devrez passer beaucoup de temps avec le débogueur : d'une part, pour trouver les erreurs, et d'autre part, pour comprendre comment tout fonctionne. Quant à la documentation, ce ne serait pas une mauvaise idée de recourir à l'archéologie industrielle. Il peut être très utile de déterrer une ancienne documentation quelque part et de parler à ceux qui se souviennent de la façon dont le code dont vous avez hérité a été écrit. En utilisant ces techniques, vous commencerez tôt ou tard à comprendre plus ou moins le code. Mais pour éviter que vos efforts ne soient vains, vous devez immédiatement documenter les résultats de vos recherches. Pour ce faire, je recommande de dessiner des schémas fonctionnels ou des diagrammes de séquence. Bien sûr, vous serez paresseux, mais vous devez absolument le faire, sinon dans six mois sans documentation, vous fouillerez ce code comme si c'était la première fois.

Ne réécrivez pas le code

La chose la plus importante dans le processus de développement est de se battre à temps et de ne pas essayer de réécrire tout le code à partir de zéro. Estimez combien d’années-homme cela nécessitera. Il est peu probable que le client veuille dépenser autant d’argent pour refaire quelque chose qui fonctionne déjà. Cela s’applique non seulement au système dans son ensemble, mais également à n’importe quelle partie de celui-ci. Bien sûr, ils peuvent vous donner une semaine pour tout comprendre et une autre semaine pour réparer quelque chose. Mais il est peu probable qu'ils vous donnent deux mois pour réécrire une partie du système. Au lieu de cela, implémentez la nouvelle fonctionnalité dans le même style que le reste du code. En d’autres termes, si le code est ancien, il ne faut pas être tenté d’utiliser de belles technologies nouvelles : un tel code sera alors très difficile à lire. Par exemple, vous pouvez rencontrer une situation comme la nôtre : une partie du système est écrite en Spring MVC et une partie est écrite en servlets nus. Et si dans une partie écrite en servlets, quelque chose d'autre doit être ajouté, alors nous l'ajoutons de la même manière - en servlets.

Respecter les intérêts commerciaux

Il ne faut pas oublier que toute tâche est déterminée avant tout par la valeur pour l'entreprise. Si vous ne prouvez pas au client la nécessité de certains changements d'un point de vue commercial, ces changements n'auront pas lieu. Et pour convaincre le client, il faut essayer de se mettre à sa place et de comprendre ses intérêts. En particulier, si vous souhaitez refactoriser simplement parce que le code est difficile à lire, vous ne serez pas autorisé à le faire et vous devrez vivre avec. Si vous ne pouvez vraiment pas le supporter, vous pouvez réorganiser le code tranquillement et petit à petit, en répartissant le travail sur les tickets professionnels. Ou convaincre le client que cela, par exemple, réduira le temps nécessaire à la recherche des erreurs et donc, à terme, les coûts.

Test

Il est clair que les tests sont nécessaires dans tout projet. Mais lorsque l’on travaille avec des systèmes existants, une attention particulière doit être accordée aux tests, car l’impact des modifications apportées n’est pas toujours prévisible. Vous aurez besoin d’au moins autant de testeurs que de développeurs, sinon vous devriez être incroyablement doué en automatisation. Dans notre projet, les tests comprenaient les phases suivantes :

1. Vérification, lorsque la fonctionnalité implémentée d'une fonctionnalité est vérifiée dans une branche distincte.
2. Stabilisation, lorsqu'une branche de version est archivée dans laquelle toutes les fonctionnalités sont fusionnées.
3. La certification, lorsque la même chose est réexécutée sur des cas de tests légèrement différents dans un environnement de certification le plus proche possible de la production en termes de caractéristiques matérielles et de configuration.

Et ce n’est qu’après avoir traversé ces trois phases que nous pourrons publier une version. Quelqu'un pense probablement que la certification est une phase supplémentaire, puisque tout a déjà été clarifié au stade de la stabilisation, mais notre expérience suggère que ce n'est pas le cas : parfois lors d'un test de régression, qui est effectué pour la deuxième fois sur une autre machine, quelque chose ça va sortir.

Formaliser DevOps et publier

La procédure de libération pourrait par exemple être la suivante. Lorsque le développement est terminé et que deux ou trois phases de tests sont terminées, nous écrivons un e-mail à l'équipe DevOps 36 heures avant l'heure de sortie prévue. Après cela, nous appelons l'équipe devops et discutons de tous les changements dans les environnements (nous les informons de tous les changements dans la base de données et la configuration). Pour chaque changement nous avons un document (un ticket dans Jira). Puis, lors de la sortie, toutes les personnes impliquées dans cela se réunissent, et chacun dit ce qu'il fait maintenant : « Nous avons téléchargé la base de données », « Nous avons redémarré tel ou tel serveur », « Nous sommes allés faire des tests de régression dans l'environnement de production. » Si quelque chose ne va pas, la procédure de restauration de la version est lancée, exactement décrite dans le document de version d'origine - sans un tel document, nous oublierons certainement quelque chose ou serons confus.

Contrôler la qualité du code

Et enfin, la révision de code est une pratique qui, pour une raison quelconque, n'est pas utilisée dans tous les projets. C'est formidable si chaque morceau de code est examiné par plus d'une personne. Même dans une équipe très solide, certains bugs sont toujours découverts lors du processus de révision du code, et si plusieurs personnes l'examinent, le nombre de bugs identifiés augmente. De plus, il arrive parfois que le troisième ou le quatrième évaluateur trouve la pire chose.

Des outils qui facilitent la rédaction de la documentation technique

Source : Dzone La plupart des programmeurs n'aiment pas rédiger de documentation technique. L'expert en psychologie Gerald Weinberg a même qualifié la documentation de « l'huile de ricin de la programmation » : les développeurs adorent la lire, mais ils détestent tout simplement l'écrire eux-mêmes. Un manque de conseils ou une feuille de route vierge entraîne un manque d'informations sur le fonctionnement des différentes parties du logiciel. Cela finit par détériorer l'expérience des utilisateurs finaux du code car, en l'absence de documentation, ils ne peuvent pas compter sur l'exactitude et l'utilité du produit. Pour permettre aux programmeurs de prendre plus facilement l'habitude de rédiger de la documentation, je recommande de prêter attention à quatre excellents outils qui sont désormais disponibles pour presque tout le monde.

Pages GitHub

Il n’y a probablement pas un seul développeur aujourd’hui qui n’ait pas d’expérience de travail sur GitHub. C'est également un endroit idéal pour les programmeurs qui ont besoin d'un endroit pour stocker la documentation. De nombreuses personnes utilisent un fichier Readme standard dans leur base de code pour fournir à l'utilisateur un guide pratique simple, mais ce n'est pas le seul moyen de créer de la documentation sur GitHub. Avec GitHub Pages , vous obtenez bien plus qu'un simple hébergement pour les pages de votre projet, y compris de la documentation et des didacticiels. Vous avez la possibilité d'interagir directement avec tous les référentiels GitHub, permettant aux développeurs de mettre à jour la documentation de la même manière qu'ils mettent à jour leur code. De plus, vous pouvez utiliser Jekyll ici - il vous aide à transformer votre balisage en texte brut ou en pages Web à part entière.

Lire les documents

Comme son nom l'indique, Read the Docs fournit aux développeurs une plate-forme pour stocker et lire la documentation. Le service fonctionne un peu comme GitHub Pages : les programmeurs peuvent apporter des modifications à la documentation à partir de leurs systèmes de contrôle de version préférés, notamment Git, Bazaar, Mercurial et autres. La gestion automatique des versions et la création de pages sont également prises en charge. La meilleure partie de Read Docs est sa flexibilité. Il prend en charge les webhooks afin que vous puissiez automatiser une grande partie du processus de création de documents. C'est un énorme gain de temps sur une tâche avec laquelle la plupart des programmeurs ne veulent rien avoir à faire. De plus, tout ce qui est hébergé sur la plateforme est accessible au grand public dans une variété de formats, notamment PDF, HTML d'une seule page et même au format livre électronique. Le service assume une part importante du travail de routine visant à maintenir la documentation à jour.

Téttra

Tettra n'est pas seulement une plateforme de stockage de documentation logicielle, mais une base de connaissances complète. Cela fonctionne particulièrement bien lorsqu'un projet implique un grand groupe de codeurs travaillant sur différents logiciels. Tettra peut être utilisé pour documenter les réponses aux questions courantes.

Rucher

Ce qui rend Apiary si utile pour les développeurs, c'est le fait qu'il facilite grandement la documentation de l'API. La plateforme permet aux utilisateurs de rédiger leur documentation en Markdown , y compris des appels d'API simulés. Apiary vous permet également de tester et de prototyper des éléments d'API. En d’autres termes, il s’agit d’un outil de documentation et d’une plateforme de test réunis en un seul endroit.