Coworker : “Let’s create some well organized and structure code “
Me :
Le code spaghetti, que pasta ?
Que l’on soit simple débutant ou codeur confirmé, le code spaghetti est un casse-tête difficile et la meilleure façon de résoudre un casse-tête, c’est de ne pas avoir à se casser la tête.
Dans cet article, je vais énoncer un ensemble d’outils, de conventions et de bonnes pratiques qui vont vous permettre d’écrire un code plus lisible et plus maintenable. Simple, basique.
Avant de rentrer dans le vif du sujet, définissons tout d’abord ce qu’est un code spaghetti.
Selon notre bible à tous Wikipédia,
En programmation informatique, la programmation spaghetti est un style d’écriture de code source qui favorise l’apparition du syndrome du plat de spaghettis : un code peu clair et qui fait un usage excessif de sauts inconditionnels (voir goto), d’exceptions en tous sens, de gestion des événements complexes et de threads divers.
Défini plus simplement, c’est un code qui ne permet pas de faciliter la maintenabilité de celui-ci: il est mal structuré, il fait des imports dans tous les sens, il n’est bien souvent pas commenté, il a tendance à dépasser les 2000 lignes et, si vraiment vous êtes malchanceux, il n’est pas indenté.
Les bases d’un code structuré
Avant de présenter quelques outils qui vont vous permettre de vous aider à mieux structurer votre code, il y a des conventions et des bonnes pratiques que vous pouvez suivre dès maintenant dont voici une petite liste ci-dessous.
1 – Respecter une convention de nommage
Lorsque vous créez un fichier ou un dossier, que vous nommez une fonction, une classe ou n’importe quelle variable, il est important de définir dès le début une convention de nommage et de s’y fixer. Il en existe plusieurs types dont voici les plus utilisées:
- Le camelCase, ou “casse de chameau” en référence aux bosses de celui-ci, qui consiste à écrire les mots collés avec une majuscule à chaque début de mot, sauf pour le premier. Comme ceci:
myVariableName. C’est une convention énormément utilisée en Javascript notamment. - Le PascalCase, ou “casse de Pascal” en référence au langage Pascal dans lequel il est le plus utilisé est identique au camelCase à la différence que le premier mot comporte également une majuscule. Comme ceci:
MyVariableName. C’est une convention qui est surtout utilisée en PHP pour les noms de classes. - Le kebab-case ou “casse de kebab”, en référence au tiret entre les mots qui font penser à une broche à kebab qui viendrait les empaler, qui consiste tout simplement à écrire les mots en minuscule et à les séparer par un tiret. Comme ceci:
my-variable-name. Cette convention est très utilisée pour nommer les attributs “class” et “id” en HTML/CSS. - Enfin, il y a le snake_case ou “casse de serpent”, en référence à l’underscore entre chaque mot qui fait penser à un petit serpent (si si, regardez bien), qui consiste donc à faire du kebab-case mais avec des underscores plutôt que des tirets. Comme ceci:
my_variable_name. Beacoup utilisée en PHP et en Python, cette convention sert également à nommer les constantes en PHP avec une petite variante, il faut tout mettre en majuscule, comme ceci:MY_CONST_NAME.
Par convention, les 4 types d’écritures ci-dessus sont plus ou moins utilisés dans tel ou tel langage, ce n’est pas grave si vous n’employez pas celui le plus utilisé par vos pairs, mais si vous en choisissez une, restez y fidèle.
2 – Bien nommer vos variables, bien indenter et bien commenter votre code
Maintenant que vous avez choisi une des conventions ci-dessus, il reste encore à bien nommer vos variables ainsi qu’à bien indenter et commenter votre code, cela vous permettra de mieux le comprendre quand vous le relirait mais également lorsque les autres le reliront.
Il faut également vous tenir à une langue lorsque vous programmez, ne mélangez pas des variables en anglais dans un fichier, en français dans un autre et ainsi de suite. Choisissez en une et pasta !
Exemple:
const a=[66,82];
var u=[{id:1,fn:"Guillaume"},{id:2,fn:"Pierre"}];
u.forEach((u,i) => u.bd=a[i]);
console.log(u);
VS
// Set ages to users
const ages = [66, 82];
const users = [
{
id: 1,
name: "Guillaume"
},
{
id: 2,
name: "Pierre"
}
];
users.forEach((user, userIndex) => user.age = ages[userIndex]);
console.log(users);
Le 2ème exemple, bien que plus long est également bien plus simple à comprendre.
Pour savoir si ce que vous écrivez est lisible, le meilleur moyen et de partager votre code à votre équipe. Celle-ci devrait pouvoir comprendre ce qu’il fait d’un simple coup d’oeil.
Vous n’êtes pas obligé de commenter chaque ligne de votre code mais si pour vous une partie de votre code est un peu plus complexe, n’hésitez pas à la commenter, si vous y retournez dans 2 mois, vous serez bien content de l’avoir fait (faites moi confiance…).
Une bonne pratique à avoir consiste également à mettre un commentaire devant chacune de vos fonctions avec ce qu’elle prend en paramètre, ce qu’elle retourne et une description rapide de ce qu’elle fait. En effet, une bonne partie des générateurs de documentation se base sur les commentaires pour créer celle-ci.
Comme ceci:
/**
* Add a number to another
* @param {int} a - First number
* @param {int} b - Second number
* @returns {int}
*/
function add(a, b) {
return a + b;
}3 – Découper votre code
Les italiens seront outrés mais pour démêler vos spaghettis, découpez les !
En effet, si vous utilisez plusieurs fois le même code ou la même fonctionnalité, n’hésitez pas à créer une fonction que vous pourrez réutiliser.
Par exemple:
const today = new Date()
var formatToday = today.toLocaleDateString({
year: "numeric",
month: "2-digit",
day: "2-digit",
});
var tomorrow = new Date();
tomorrow.setDate(today.getDate()+1);
var formatTomorrow = tomorrow.toLocaleDateString({
year: "numeric",
month: "2-digit",
day: "2-digit",
});
console.log(`Aujourd'hui nous sommes le ${formatToday} et demain nous serons le ${formatTomorrow}`);
VS
/**
* Return formatted date
* @param {Date} date - Date to format
* @returns {string} - Formatted Date
*/
function formatDate(date) {
return date.toLocaleDateString({
year: "numeric",
month: "2-digit",
day: "2-digit",
});
}
const today = new Date();
var tomorrow = new Date();
tomorrow.setDate(today.getDate()+1);
console.log(`Aujourd'hui nous sommes le ${formatDate(today)} et demain nous serons le ${formatDate(tomorrow)}`);4 – Utiliser les recommandations de votre langage
Chaque langage possède des recommandations spécifiques à suivre, cela peut aller de la simple convention pour positionner les accolades de vos fonctions à l’architecture même d’une requête HTTP.
Voici quelques exemples de standards de recommandations les plus connus:
Les PSR en PHP ou PHP Standard Recommandation
Les PSR sont un ensemble de spécifications écrites par le PHP Framework Interop Group, il y en a actuellement 20, du PSR-0 au PSR-19 mais seulement 13 sont encore valables, les autres étant soit en attente de validation, soit obsolètes.
Leurs utilisation permet de standardiser les concepts de programmation. Pour faire court, il y a parfois plusieurs façons d’écrire un code et le PSR va choisir celui qui est le plus optimisé. Par la suite, si chaque développeur suit ces recommandations, nous allons retrouver plus ou moins la même manière d’écrire du code d’une application à une autre, ce qui va permettre une meilleure compréhension de celui-ci.
Vous pouvez retrouver une liste de ces PSR et de leur application ici.
Les recommandations Airbnb en JavaScript
Vous pourrez retrouver à cette adresse une liste des recommandations pour écrire du JavaScript réalisé par Airbnb. Ce sont des recommandations qui sont quand même très contraignantes mais qui permettent d’écrire un code plus optimisé. Je vous recommande d’y jeter un oeil si vous codez majoritairement en JavaScript et de prendre connaissance de la plupart des recommandations, à vous de choisir ceux que vous voulez suivre.
Le TypeScript
TypeScript est un sur-ensemble de JavaScript qui a pour but d’améliorer votre code. Il va vous permettre notamment de rajouter du typage à JavaScript, ainsi un code qui ressemble à ceci en JS:
var myBoolean = false;
var myString = "Hello World";
var myNumber = 1;
var myFunction() {
return "My String";
}
Ressemblera à ceci en TS:
// Création d'une variable contenant une valeur booléenne.
var myBoolean: boolean = false;
// Création d'une variable contenant une chaîne de caractère.
var myString: string = "Hello World";
// Création d'une variable contenant un nombre.
var myNumber: number = 1;
// Création d'une fonction retournant une chaîne de caractère.
function myFunction(): string {
return "My String";
}
Cela améliore la compréhension de votre code mais également la qualité de celui-ci. Je vous invite à aller regarder la documentation ici ainsi qu’à tester par vous même.
5 – Bien architecturer votre projet
Maintenant que vos fichiers sont bien nommés, que votre code est clair et bien découpé, il reste une dernière étape: bien architecturer votre projet. C’est simple, on ne mélange pas les farfalles avec les cannellonis !
Petit exemple d’architecture de projet avant et après tri.
Avant:
Après:
Il est ainsi beacoup plus simple de se repérer dans le projet pour vous mais également pour les autres et plus le projet prendra de l’ampleur, plus l’architecture de celui-ci sera importante.
Les outils disponibles pour nous aider
Pour nous aider dans notre quête d’un code plus maintenable et plus lisible, il existe un ensemble d’outils qui est mis à notre disposition. Le premier, le plus utilisé et le plus connu:
L’IDE ou environnement de dévelopement
Si vous ne savez pas ce qu’est un IDE, je vous renvoie à sa définition ici.
Un bon IDE va en effet nous permettre de voir rapidement lorsqu’il manque un import, lorsqu’une variable est définie mais pas utilisée ainsi que plein d’autres aides utiles, telle qu’une documentation intégrée pour les fonctions natives ou encore une aide pour résoudre les chemins vers vos fichiers.
Pour les exemples ci-dessous, j’utilise VSCode, mais il y a d’autres IDE qui font aussi très bien l’affaire tel que IntelliJ IDEA, Xcode ou encore PHPStorm.
Exemple de documentation intégrée:
Exemple de résolution de chemin:
Il existe également des plugins disponibles pour la plupart des IDE qui vont vous faciliter la programmation tels que les surligneurs syntaxiques, l’autocomplétion, les snippets (ou fragments de code) et tant d’autres, c’est à vous de faire votre petit marché dans la bibliothèque des plugins.
Le Marketplace de VSCode:
Les linters
Le second outil qui pourra nous aider s’appelle un linter, je vous renvoie également vers la définition pour savoir de quoi il en retourne mais grossièrement expliqué, c’est un ensemble de règles qui vont être appliquées à votre code et dans le cas ou vous ne les respectez pas, ce linter va vous retourner sous forme d’erreurs et de warnings les erreurs rencontrées.
L’un des linters les plus connus est un linter JavaScript, son nom ? ESLint. Et voici quelques exemples d’erreurs q’un linter peut vous retourner.
Pour mes exemples, je vais utiliser le linter ESLint.
Pour l’installer, c’est très simple, il faut que vous ayez NPM installé sur votre ordinateur, pour savoir si NPM est installé, lancez la commande npm -v dans un terminal.
Si il est installé, vous devriez avoir un numéro de version qui s’affiche, sinon vous aurez un joli command not found
Si vous êtes dans le second cas, allez installer la LTS de Node ici, NPM est inclus avec.
Ensuite, dans la racine de votre projet, lancez la commande npm init afin d’initialiser un fichier package.json dans votre projet.
Lancez ensuite l’installation de ESLint avec la commande npm install eslint --save-dev, pas besoin de linter en production.
Enfin, lancez la commande npx eslint --initpour créer un fichier de configuration ESLint, par défaut il y a des règles tels que no-unused-vars qui lance une erreur lorsqu’une variable n’est pas utilisée par exemple.
On peut également en rajouter d’autres et pour cela, ça se passe dans le fichier de config à la clé rules.
Pour ma part, voilà à quoi il ressemble:
{
"env": {
"browser": true,
"es6": true
},
"extends": "eslint:recommended",
"globals": {
"Atomics": "readonly",
"SharedArrayBuffer": "readonly"
},
"parserOptions": {
"ecmaVersion": 11,
"sourceType": "module"
},
"rules": {
"prefer-const": "error",
"no-const-assign": "error"
}
}
J’ai rajouté 2 règles dans rules avec les clés no-const-assign et prefer-const auxquels j’ai passé la valeur error.
Cela veut dire que mon linter me lancera une erreur si j’utilise une var ou un let alors que j’aurais pu utiliser une const et qu’il me lancera également une erreur si j’essaye d’assigner une nouvelle valeur à une const.
Les autres valeurs disponibles avec error sont warning et off, qui vont respectivement déclencher une alerte pour l’une et désactiver la règle pour l’autre.
Vous pourrez trouver la liste de toutes les règles disponibles ici.
Erreur de variable non utilisée:
Erreur d’assignement de const:
Les linters peuvent parfois être contraignants mais ils sont un moyen efficace pour vous permettre d’améliorer l’écriture de votre code.
On apprend des critiques, pas des louanges.
En conclusion
On pourrait être tenté de penser qu’il y a des milliers de façons différentes de coder et nous aurions raison mais il y en aura toujours beaucoup moins pour bien coder et c’est là qu’est la différence entre un “bon codeur” et un “mauvais codeur”.
Au cours de cet article, j’ai énuméré un ensemble de conventions, de règles et d’outils qui devrait vous permettre de faire partie de la catégorie “bon codeur” mais attention, même en respectant des recommandations et en utilisant des outils, il peut toujours nous arriver de réaliser du code spaghetti.
Après tout, le meilleur outil pour bien coder, c’est vous.
