Identifier les conventions

Le plus simple est de commencer avec les règles admises par la communauté. Vous pouvez très bien adopter des conventions CSS pour du code Javascript, c’est votre droit d’écrire parse-int(), mais il est plus sage de suivre la communauté comme base tout simplement car vous allez avoir besoin de lire le code des autres auteurs soit sur github soit tout simplement pour corriger un packet npm, enfin si vous posez une question sur un forum d’aide comme stackoverflow avec des conventions décalées, peut-être que les gens ne vous prendront pas au sérieux. Donc en Javascript en écrit parseInt(), c’est du camelCase. Les conventions vont plus loin que le nommage des fonctions, des classes, des constantes, du point-virgule en fin de ligne, du retour à la ligne dans un array ou un objet. Tous ces points sont très communs à tous les projets et il est prudent de prendre les conventions de la communauté, voici quelques exemples:

A partir de cette base, vous pouvez compléter par les conventions propres à votre projet. La limite de caractères à 80 vous contraint trop ? Discutez-en avec votre équipe et définissez le nombre qui vous correspond. Une limite à 120 par exemple rentre très bien dans un écran de 13" au sein de votre IDE préféré (j’utilise Sublime Text 3, d’autres Atom ou Webstorm ou encore Vim). De même vous pouvez définir ce qui doit être commenté et ce qui ne doit pas ou la façon de les rédiger. A titre d’exemple, voici quelques conventions que nous avons autorisées dans notre projet en s’étant basé sur les conventions de Airbnb: le retour hétérogène des fonctions, les fonctions console.log et alert côté client et quelques variables globales très spécifiques.

Vos conventions peuvent également interdire les mauvaises pratiques. Qu’y a-t-il dans la variable “data” ? Seul son développeur l’a su le jour de sa création, depuis il a oublié et doit relire toute la fonction ou, pire, tout le fichier pour comprendre sa signification. Interdire les mots valise data, type, info, image, text, string, array, content, item, list a du sens. Qu’y a-t-il dans la variable string ? Une chaîne de caractère, mais encore ? Peut-être que userAvatarURL ou userProfilLink sont plus appropriés.

items.map(data => data.username) // non

users.map(user => user.username) // oui

Des noms clairs font gagner quelques milli-secondes à la lecture, ce n’est pas beaucoup dans une journée, sauf qu’en diminuant l’effort à fournir pour comprendre le code, donc les capacités cognitives, le développeur sera moins fatigué et le code plus lisible tout simplement.

Evoluer en fonction du projet

Les conventions ne sont pas seulement l’écriture de code, mais aussi sa structure, l’arborescence des fichiers. Personne ne vous indiquera si vous devriez mettre tous les contrôleurs dans un seul répertoire avec les modèles dans un autre ou chaque contrôleur avec son modèle dans un dossier pour former un “module” ou un “composant”. Voici quelques idées en fonction de la taille du projet:

Pour moins de 10 fichiers, un seul dossier est suffisant et on peut mettre un suffixe à chaque fichier pour connaître sa fonction: login.controller.js et login.view.js par exemple qui côtoieront account.model.js juste à côté.

Le projet évolue et on atteint 30 fichiers, on découpe alors en dossiers par composant avec les modèles à la racine.

Et ainsi de suite on peut créer des ensembles de composants, par exemple tout ce qui touche à l’utilisateur ira dans account: son modèle, ses composants login, profil, session, emails, etc.

Au bout d’un moment il faut arrêter de créer des dossiers, c’est le projet lui-même qui doit être découpé, plusieurs possibilités sont offertes: séparer la vue de l’API si c’est une application web, faire des modules npm réutilisables par exemple un module de recherche, d’envoi d’emails, de cache pour les images avec redimensionnement à la volée, etc. Si ils sont assez génériques vous pouvez même les proposer à la communauté, c’est comme cela qu’elle s’agrandie, grâce à vous :)

+ models

+ account.model.js

+ event.model.js

+ blog.model.js

+ composants

+ account

+ account.controller.js

+ account.view.js

+ account.css

+ account.mails.js

+ event

+ event.controller.js

+ event.view.js

+ event.css

+ blog

+ blog.controller.js

+ blog.view.js

+ blog.css

+ services

+ mail.service.js

+ db.service.js

+ cache.service.js

+ test

+ doc

+ ...

+ index.js

Dans l’exemple ci-dessus, chaque fichier a un suffixe pour connaître son contenu quand il est ouvert dans l’éditeur, on se perd facilement avec les onglets si tous les fichiers s’appellent “account.js”. C’est ce qu’on a décidé ensemble dans mon équipe car nous avions ce besoin.

N’hésitez pas à refactoriser, passer de l’un à l’autre en déplaçant les fichiers, modifiant les références et en profitant pour nettoyer le code qui n’est plus utilisé. Ensuite, profitez de votre nouvelle hiérarchie pendant un moment avant le prochain changement. Votre projet vie et évolue. Par ailleurs les tests de votre projet seront à ce moment très rentables et vous saurez si ils couvrent suffisamment de code.

Appliquer par l’équipe

Si une chose doit être gardée à l’esprit dans un projet, c’est sa maintenance. Si les conventions ne sont pas suivies ou ne sont tout simplement pas définies, chaque membre de l’équipe va avoir tendance à appliquer ses propres règles, et il est alors plus difficile pour une autre personne de maintenir le code qui a été écrit car il y aura une perte de repères: où passé ce fichier qui était là la semaine dernière ? Pourquoi cette fonction utilitaire est dans la vue plutôt que dans un fichier utils.js ? Pour un grand projet on ne s’en sort plus et on passe du temps à chercher, c’est de la frustration inutile qui pourrait être supprimée avec les conventions communes. Comme si vous vous étiez dupliqué afin de travailler sur un projet. C’est l’art de vivre ensemble en communauté en partageant des règles. Avec un seul but: être efficace. Pour être acceptées par tout le monde, quoi de mieux que la démocratie, chacun donne son point de vue et un compromis est trouvé, la convention peut être appliquée. Les outils comme eslint peuvent ensuite indiquer au développeur s’il a oublié telle ou telle chose dans son code en plus de la revue par le reste de l’équipe.