Nicolas Potier
Fondateur Associé chez ACSEO à Aix-en-Provence.
Organisateur (avec d'autres) des sfPot sur Aix/Marseille
Commentaires
Mettre les mains dans un projet existant
Dans la vie d'un développeur, il existe des projets que l'on commence à
partir de zéro et des situations dans lesquelles on est amené à reprendre
un projet existant.
Et les projets existants c'est comme les boites de chocolats 🍫, on ne
sait jamais sur quoi on va tomber...Dans cet article, nous allons passer
en revue les différents outils et conseils pour démarrer du bon pied
la reprise d'un projet.
Salarié arrivé dans une nouvelle entreprise, prestataire prenant la place d'un autre, il existe un grand nombre de situations qui nous emmènent à repartir d'un code source existant.
On peut avoir de la chance, et tomber sur LE projet, utilisant les dernières versions des différentes composants, bien documenté, avec des tests couvrant la majeure partie du code, des spécifications fonctionnelles à jour, un environnement de versionning et de CI aux petits oignons, etc. Et puis on peut tomber sur de vrais projets, avec leurs qualités et leurs défauts, qu'il va falloir comprendre et maitriser avant de commencer à produire de la valeur ajoutée.
Sommaire
Par où commencer
Vous avez de la chance, vous êtes sur Symfony
Comme vous le savez probablement, l'avantage de Symfony comme de nombreux Frameworks est qu'il offre une architecture normalisée que l'on retrouve majoritairement sur l'ensemble des projets.
Même si le Framework est assez souple pour que l'on puisse changer cette architecture, la majorité des projets que vous rencontrerez aura la même structure, ce qui facilite une reprise.
J'aime bien dans un premier temps faire un premier tour en surface pour prendre connaissance des dossiers et des fichiers, et commencer à comprendre la logique de mes prédécesseurs. Cela permet de sentir les choses.
Passage en revue de ce que vous avez à votre disposition
Selon les circonstances, vous aurez à votre disposition plus ou moins d'élements afin de reprendre votre projet. Nous laisserons de côté dans la suite de cet article des éléments écrits (spécifications fonctionnelles, document d'architecture, etc.) qu'il convient bien sûr de lire avant de démarrer l'exploration du code.
Vous pouvez donc avoir sous la main :
- De la documentation : docs, slides, PDF, emails (😱), qui vous permettront de comprendre le projet et son contexte.
- Le code source du projet : sinon on se demande bien comment on pourrait faire.
- Des données : que ce soit des exports de bases, des fixtures, des fichiers à importer.
- L'historique Git : qui comme on le verra peut s'avérer être un excellent outil pour mieux comprendre le projet.
Bien entendu, plus vous avez d'éléments, plus simple sera la reprise. Notre but sera donc de partir des moyens mis à notre disposition pour produire, grâce à des outils, des informations pertinentes qui nous permettront de mieux nous situer face au projet.
Les outils pour analyser l'existant
Notre objectif va consister ici à utiliser des outils en complément d'une analyse manuelle du projet afin de pouvoir dresser un mode opératoire pour reprendre le projet dans de bonnes conditions.
Pour commencer
Les tests bien sûr
Si il existe une chose qui peut nous donner des informations, ce sont des tests bien écrits. Qu'ils soient écrits avec Behat, PHPUnit, ou autre, la présence de tests révèle souvent les parties du projet les plus complexes.
Comprennez les tests, et vous comprendrez comment fonctionne le projet. Et si il n'y a pas de tests, vous savez ce qu'il vous reste à faire...
Compter les lignes de code
L'utilitaire cloc permet d'obtenir rapidement une vision de la taille du code source par type de fichiers et du rapport code / commentaires.
$ cd /path/to/project
$ cloc . --exclude-dir=vendor,test,var
329 text files.
320 unique files.
47 files ignored.
github.com/AlDanial/cloc v 1.72 T=4.63 s (62.4 files/s, 35069.2 lines/s)
-------------------------------------------------------------------------------
Language files blank comment code
-------------------------------------------------------------------------------
HTML 19 712 229 32983
XML 10 239 0 29579
PHP 130 5905 6040 28582
JavaScript 28 2684 2039 23411
Twig 55 3138 12 12270
CSS 20 1839 234 10700
Sass 9 228 0 928
YAML 11 54 31 259
JSON 2 3 0 97
Markdown 2 18 0 45
Python 1 6 1 32
Bourne Shell 1 9 0 25
Ruby 1 10 11 10
-------------------------------------------------------------------------------
SUM: 289 14845 8597 138921
-------------------------------------------------------------------------------Afficher le graphe Git
Git peut être une mine d'information sur le projet, qu'il est relativement facile d'exploiter. Nous verrons que quelques outils et commandes nous permettent de tirer profit de l'historique du projet.
La commande ci-dessous vous permettra d'avoir une visualisation dans votre terminal du graphique Git des commits, avec les dates et les auteurs.
$ git log --all --decorate --oneline --graph --date=short \
--pretty='%C(red)%h%Creset | %C(yellow)%ad%Creset | %C(green)%an%Creset | %s'
Ce qui produira le résultat ci-dessous :
Savoir qui a contribué au code
Si vous êtes en contact avec les précédents développeurs du projet, vous pouvez utiliser la commande ci-dessous pour lister les principaux contributeurs au projet. Ils pourront peut être vous aider ou vous éclairer en cas de questions.
$ git shortlog -s -n -e | head Connaitre les fichiers les plus commités / les plus sensibles
ArcheoloGit est un outil de visualisation de l'âge et de l'activité des fichiers versionnés. L'outil produit une carte des différents fichiers. Chaque fichier est représenté sous la forme d'un rectangle, dont la taille est proportionnelle au nombre de commits. La couleur des rectangles dépend de la dernière date de modification du fichier.
Nous utiliserons docker par simplicité pour lancer l'outil :
$ cd /path/to/project
$ docker run -it --rm -v $PWD:/data:ro -p 8001:8000 clue/archeologit
Number of files: 315
>100%
Serving HTTP on 0.0.0.0 port 8000 ...
Ce qui produira le résultat ci-dessous :
- Les grands rectangles rouges montrent des fichiers modifiés souvents, mais qui n'ont pas été touchés depuis longtemps. Ils nécessitent une certaines attention afin de voir si un refactoring n'est pas nécessaire.
- Les petits rectangles rouges montrent les fichiers rarement modifiés, et depuis longtemps. Ils sont peut être sans importance, ou peut être contiennent des bombes à retardement.
- Les petits rectangles verts montrent des fichiers modifiés rarement, mais créés ou modifiés récemment. Il n'est peut être pas nécessaire de s'y pencher dès le début.
- Les grands rectangles verts montrent des fichiers modifiés souvents, et récemment. Il n'est sans doute pas nécessaire de s'y pencher maintenant.
Pour approfondir
SensioLabs Security Check
SensioLabs Security Check est un outil qui analyse le fichier composer.lock de votre projet à la recherche d'éventuelles failles de sécurité dans les packages qui le composent.
L'outil est très facile à utiliser, autant ne pas s'en passer.
$ cd /path/to/project
$ docker run -it --rm -v "$PWD":/app -w /app adamculp/php-security-checker:latest \
php /usr/local/lib/php-security-checker/vendor/bin/security-checker security:check \
./composer.lock
Symfony Security Check Report
=============================
// Checked file: /app/composer.lock
[ERROR] 1 packages have known vulnerabilities.
symfony/symfony (v3.3.6)
------------------------
* CVE-2017-16653: CVE-2017-16653: CSRF protection does not use different tokens for HTTP and HTTPS
http://symfony.com/blog/cve-2017-16653-csrf-protection-does-not-use-different-tokens-for-http-and-https
* CVE-2017-16654: CVE-2017-16654: Intl bundle readers breaking out of paths
http://symfony.com/blog/cve-2017-16654-intl-bundle-readers-breaking-out-of-paths
* CVE-2017-16790: CVE-2017-16790: Ensure that submitted data are uploaded files
http://symfony.com/blog/cve-2017-16790-ensure-that-submitted-data-are-uploaded-files
* CVE-2017-16652: CVE-2017-16652: Open redirect vulnerability on security handlers
http://symfony.com/blog/cve-2017-16652-open-redirect-vulnerability-on-security-handlers
! [NOTE] This checker can only detect vulnerabilities that are referenced in
! the SensioLabs security advisories database. Execute this command
! regularly to check the newly discovered vulnerabilities.SensioLabs Insight
Si votre projet est Open Source, ou si vous disposez d'un compte payant, vous pouvez utiliser SensioLabs Insight. Il s'agit d'un outil permettant de mesurer la qualité du code.
Vous disposerez ainsi de nombreux éléments indicatifs sur le code source,
sous divers aspects allant de la sécurité aux best pratices de développement.
Un outil pour les lancer tous
Il existe une panoplie d'outils permettant de mesurer la qualité du code PHP sous toutes ses formes. PHPQA regroupe simplement ces outils les plus utilisés afin de centraliser leur exécution.
En une seule ligne de commande, vous pourrez ainsi lancer les outils suivants
- phploc
- phpcs
- php-cs-fixer
- phpmd
- pdepend
- phpcpd
- phpstan
$ cd /path/to/project
$ docker run --rm -u $UID -v $PWD:/app eko3alpha/docker-phpqa --report \
--ignoredDirs vendor,build,migrations,test \
--tools phpqa,phpmetrics,phploc,phpcs,php-cs-fixer,phpmd,pdepend,phpcpd,parallel-lint,phpstan
Le résultat de la commande construit des rapports au format HTML pour chacun des outils lancés. Chaque onglet vous donnera de nombreuses indications sur l'état du code.
Et maintenant, on fait quoi ?
Grâce à tous ces outils, vous avez beaucoup d'informations à votre disposition et surtout vous devriez y voir plus clair sur l'état du projet que vous ne connaissiez pas il y a peu.
En fonction de ce que vous aurez pu voir, je vous invite à classer les actions à mettre en oeuvre selon 3 catégories.
Les actions à faire avant toute chose
Il s'agit des travaux que vous devez mener avant de produire une ligne de code supplémentaire. Parmi ces actions, je pense notamment aux choses suivantes :
- Mettre à jour des composants présentant des failles de sécurité avérées.
- Modifier du code exposant des failles de sécurité (le petit SQL natif caché au fond d'un dossier et sans échappement).
- Harmoniser le code.
- Faire tout ce qu'il faut pour que la structuration des données soit bonne.
- Vérifier que la documentation permettant d'installer le projet est complète.
- Mettre en place ou compléter les outils de suivi de la qualité du projet (allant du hook git à une CI complète).
Les actions qui amélioreront le projet et votre efficacité
En fonction du temps que vous avez à votre disposition, vous pourrez mettre en place d'autre actions avant de commencer, ou intégrer ces actions dans les développements ultérieurs.
Ces actions doivent vous mener à disposer d'un projet de meilleure qualité, plus facile à maintenir, et allant dans le sens d'un schéma directeur que vous aurez préalablement défini.
Ces actions peuvent être du type :
- Supprimer les redondances de code.
- Refactoriser le code pour que celui-ci corresponde à la logique Métier de votre projet.
- Réduire le couplage entre les composants, mettre en place des librairies et des services là ou c'est nécessaire.
- S'appuyer sur les possibilité offertes par le Framework ou ses Bundles plutôt que de réinventer la roue.
- S'assurer que les composants utilisés sont pertinents, à jour et maintenus.
- Faire si possible des montées en version sur ces dépendances, pour aller sur les version LTS.
- Passer en revue les fichiers les plus critiques (cf. Archeologit) pour développer des tests unitaires et fonctionnels.
Les actions à faire "pour se faire plaisir"
- Faire des montées de versions majeures, en vérifiant bien sûr de ne rien casser en passant...
- Utiliser une ou des nouvelles technos en replacement progressif de certaines parties de l'appli.
- Mettre en place le projet idéal tel qu'il a été décrit en début de cet article 😊.
Conclusion
Pour conclure, j'espère que vous trouverez dans cet article des informations que vous pourrez piocher à l'avenir. Reprendre un projet existant n'est pas obligatoirement une chose rébarbative, et avec quelques outils et un peu de méthodologie on peut en faire une expérience satisfaisante.
Vous avez d'autres façons de faire, un avis sur ces outils ? N'hésitez pas à commenter cet article !
10 Décembre
