Introduction
Il y a quelques semaines, j’ai posté quelques conseils afin d’optimiser un seul projet GitHub. Ces conseils ayant été appréciés, je les regroupe ici en vous préparant la suite.
Mon concept de bonne réalisation
Par un projet bien réalisé, j’entends différentes choses :
- La documentation du projet, dans sa globalité, pour soi-même une future personne, mais aussi technique.
- Le normage des commits, de l’ensemble du code, des branches.
- L’absence de code, ou commentaire polluant.
La documentation
La documentation globale
La documentation, c’est celle qui raconte et explique ton projet.
Idéalement, elle sert autant à toi qu’aux personnes qui jetteront un oeil à ton repos que ce soit pour de la review de code, de la participation, ou de la curiosité.
Le README.md
Le README, c’est LA BASE de ton projet, celle qui en fait la pub, qui est visible directement en arrivant sur celui-ci. Pourquoi donc le négliger ?
Le contexte du projet
On raconte l’histoire du projet, ce pourquoi il a été fait, dans quel(s) but(s), avec quel(s) enjeu(x).
- Pour toi, en regardant de nouveau ton projet dans quelques semaines ou quelques mois, ça aidera à ta mémoire.
- Pour les autres, avoir du contexte, c’est comprendre l’existence même du projet, ainsi que son but.
L’installation du projet
Hé oui, si quelqu’un veut le faire tourner sur sa machine, pour x ou y raisons, ce serait sympa de savoir comment faire. Idéalement en pensant, que tout le monde n’est pas sur un OS Linux (Bouh). Avec la creation de la base de données, des variables d’environnements, etc…
L’architecture du projet
C’est connaitre le sens de fonctionnement de celui-ci, c’est faire un petit rappel à soi-même et aux autres des patterns aussi. Apprendre et reviser la théorie, c’est bon pour tout le monde !
Le fonctionnement du projet
Qu’est-ce que se passe-t-il quand on lance le projet sur sa machine ? Faut-il se créer un compte utilisateur ? Sur quel onglet faut-il cliquer pour avoir accès à telle fonctionnalité ? Etc…
Toi et le projet
La partie qui pour moi, et la plus importante pour toi ! Faire le point sur ce sur quoi le projet t’a apporté, ce que tu as appris avec, les difficultés et réussites que tu as eu dessus. C’est vraiment pas deconnant ça, car tu vas apprendre à prendre du recul sur toi même, chose qui est loin d’être évidente, tu vas noter et concrétiser aussi, tout ce travail accomplis et comprendre que ouais, t’as trop géré en fait, même si sur x tâche t’en as chier, parce que t’es BG !
La documentation technique
Le README.md
Dans le cas où tu as un repos global pour un projet en frontend, un second en backend, voir davantage de sous projets, réécrire l’installation, et le lancement du sous projet peut être nécessaire.
Ton code
Plusieurs outils existent pour documenter ton code, que ce soit les classes, les fonctions, les APIs, pas mal de choses existent pour te faciliter le travail et franchement ce serait dommage de s’en priver.
Attention on parle de documentation, et non de commentation du code hein. Oui j’invente des mots pas beaux, mais c’est pas grave.
Le nommage
Le nommage, le bon nommage, le beau, le propre, c’est un nommage qui est explicite.
Explicite:
Suffisamment clair et précis dans l’énoncé ; qui ne peut laisser de doute.
Le code
Une variable bien nommée, c’est une variable dont on comprend l’existence par son nom, sans regarder ce quelle contient.
Une fonction bien nommée, c’est une fonction dont on comprend l’intention, ce qu’elle va réaliser.
La même chose pour ta classe, etc…
Les commits
Le bon nommage des commits, que ce soit pour toi-même ou lorsque tu vas bosser en équipe ça aide énormément. C’est savoir où tu as bossé, dans quel but, et ce que tu as réalisé.
Entre nous, prendre le plis, ce n’est pas évident, mais à force ça se fait automatiquement, comme n’importe quelle habitude.
En général, les entreprises suivent les mêmes conventions, lorsque tu travailles sur un projet à toi d’en choisir, voir même de les définir.
Les branches
Tout pareil que pour les commits. Ouf un pavé en moins.
Les commentaires
Après mes post, je suis tombé sur un réel insta, d’une developpeuse qui invitait à commenter TOUT le code. Alors non. N. O. N.
NON.
Si tu as réalisé de fil en aiguille ce qu’on a dit précédemment, en fait, les commentaires on en a pas besoin. Héhé.
On va en avoir besoin, pour des exceptions, des bouts de codes qui sont peut être complexes, et là oui peut être faudrat-il mettre un commentaire pour expliquer, mais ce doit être exeptionnel, et montre peut être un manque de découpage, de refacto.
Les bouts de code entiers qui sont commentés, alors ça, c’est niet. Personnellement, ça me fait toujours pleurer des larmes de sang (oui je suis dans l’abus mais bon). Si tu n’as plus besoin d’un bout de code, ça saute, Hop hop ! Au pire, tu le commite, et suppr ensuite, avec un bon nommage de commit ce sera EZ de le retrouver.
Tout ça in english please
Pas évident quand on parle english comme moi, mais on force, on ne sait pas qui verra le projet demain, et en se forçant, on apprend. Letseuh go !
Ressources et Outils
La documentation
Pour générer de beau README.md facilement => https://readme.so/fr
Une extension VSCode pour générer la documentation de ton code => https://marketplace.visualstudio.com/items?itemName=mintlify.document
Pour documenter ton API => https://swagger.io/specification/ et/ou https://github.com/nelmio/NelmioApiDocBundle
Le nommage
Pour nommer tes commits => https://www.conventionalcommits.org/en/v1.0.0/ ou https://karma-runner.github.io/6.3/dev/git-commit-msg.html (merci à Anouchka Maurer sur LinkedIn du partage)
Pour nommer tes branches gits => https://danielkummer.github.io/git-flow-cheatsheet/ ou l’antisèche Git de @c_chaudier (Twitter) que tu retrouves ici https://froggit.fr/communaute/
La qualité globale
Bonus pour terminer tout ça => https://www.sonarqube.org/ qui va t’apprendre bien des choses sur ton propre code.
Bonus
Dédicasse (on est d’accord j’fais boomeuse avec ce mot?) à Lorenzo qui a été inspiré par mon thread sur Twitter et d’autres personnes, et a écrit un article que tu trouvera ici => https://ilovecode.co/post/hygiene-et-developpement