Au cours des cinq dernières années, j'ai constamment tenté d'améliorer mes compétences en codage, et l'une d'entre elles consistait à apprendre et à suivre les styles de codage les plus recommandés.
Ce guide vise à vous aider à écrire du code cohérent et élégant et comprend quelques conseils pour améliorer la lisibilité et la maintenabilité du code. Il s'inspire des directives populaires les plus acceptées au sein de la communauté, mais comporte quelques modifications pour mieux s'adapter à mes préférences.
Il convient de mentionner que je suis un développeur JavaScript full-stack et que toutes mes notes sont spécifiques à ma pile technologique (MEVN) et peuvent ne pas être applicables à d'autres piles.

Règles générales

Évitez la duplication de code

S'il est nécessaire d'écrire le même bloc de code (ou avec quelques différences gérables) à plusieurs endroits, il est essentiel de les fusionner dans une fonction et, par la suite, d'appeler la fonction à chaque fois nécessaire.

Envisagez un couplage lâche

Les fonctions doivent fonctionner indépendamment, ce qui signifie que la modification de l'une d'entre elles ne devrait avoir absolument aucun effet sur les autres tant que les entrées et les sorties restent les mêmes. Chaque fonction ne doit avoir aucune connaissance des définitions des autres et fonctionner comme un composant distinct. Dans cette situation, tout ce qu'il connaît, ce sont ses paramètres, et peu importe qui appelle la fonction, les mêmes entrées renvoient toujours les mêmes résultats.

Déclaration

Avant toute chose, pensez à déclarer les variables à tout moment.
Utilisez le mot-clé const lorsqu'une variable ne sera pas réaffectée. Cependant, vous pouvez toujours utiliser const pour les variables qui sont des objets ou des tableaux, même si vous envisagez de réaffecter leurs éléments imbriqués.
Veuillez noter qu'il faut exiger des modules et définir des variables constantes toujours en utilisant le mot-clé const.
Utilisez le mot-clé let lorsque vous ne pouvez pas utiliser const, et n'utilisez le mot-clé var que si vous devez prendre en charge des navigateurs plus anciens.

Fonctions

Les fonctions doivent être limitées aux éléments suivants :

• Quatre variables
• Quatre paramètres
• Trente lignes de code (en ignorant les commentaires)
• Quatre branches (if-else, while, for, or-and, switch-case)

Les lignes de code doivent être limitées à 100 caractères, et afin de regrouper/organiser les fonctions, il est préférable de garder les fonctions associées proches les unes des autres autant que possible.
Privilégiez la syntaxe de la fonction flèche à l'alternative traditionnelle chaque fois que cela est possible.

Cordes

Utilisez des guillemets simples ' (plutôt que des guillemets doubles ") pour les littéraux de chaîne ordinaires, mais pour les chaînes avec des variables/expressions intégrées, des chaînes sur plusieurs lignes et des chaînes contenant des guillemets simples, utilisez des littéraux de modèle.

Appellation

Il est essentiel de maintenir la cohérence lors de la dénomination des variables. Cela signifie que si des variables sur différentes pages sont responsables des mêmes données, elles doivent avoir le même nom.

Les noms des variables, des fonctions, des méthodes et des paramètres doivent être auto-descriptifs, ce qui signifie que n'importe qui devrait être en mesure de connaître (ou au moins de deviner) les données contenues simplement en regardant leurs noms.

Les variables constantes doivent être en majuscules, avec des mots séparés par des traits de soulignement. Les fonctions, variables et méthodes doivent suivre la syntaxe camelCase, tandis que les classes et identifiants CSS doivent suivre la syntaxe kebab-case.

Commentaires

Les commentaires doivent toujours commencer par une lettre majuscule et être limités à 100 caractères. Vous vous souviendrez peut-être que les lignes de code suivraient la même règle, mais notez que si les lignes incluent les deux, elles ne peuvent dépasser 150 caractères.
Les commentaires décrivant les fonctions ne doivent pas être écrits là où elles sont appelées mais là où elles sont définies.

Placez les commentaires après les codes sur une ligne, sauf si la longueur de la ligne dépasse 150 caractères. Dans de tels cas, et pour les codes multilignes, placez les commentaires en haut.

Concernant les instructions if, les commentaires doivent être placés après les instructions conditionnelles.

if (conditionIsTrue) { // Put your comment here
    doSomeThing();
} else { // Put your comment here
    doSomethingElse();
}

N'oubliez pas d'utiliser des doubles barres obliques // pour les commentaires sur une ligne et /* */ pour ceux sur plusieurs lignes. Lorsque vous ajoutez des commentaires sur plusieurs lignes à du code sur une ligne ou à des instructions conditionnelles, placez-les dans /* */ de sorte que /* soit écrit devant le code, que le commentaire commence sur la ligne suivante et que */ soit écrit sur un nouveau doubler.

if (conditionIsTrue) { /*
        Put your comment here
        Put your comment here
    */
    doSomeThing();
}

functionName(parameter), /*
    Put your comment here
    Put your comment here
*/

Commentaires descriptifs de la fonction

Placez les commentaires au-dessus des fonctions enveloppées par /** */.

• Décrivez les paramètres à l'aide de la description @param {type} variableName.
• Si le paramètre peut accepter plusieurs types de variables, utilisez @param {type1 | type2} description du nom de la variable.
• Si le paramètre est facultatif et pourrait être absent, utilisez la description @param {type} [variableName].
• Si le paramètre a une valeur par défaut (il doit être facultatif pour pouvoir effectivement avoir une valeur par défaut), utilisez la description @param {type} [variableName="value"].
• Décrivez la sortie de la fonction à l'aide de la description @returns {type}.

/**
 * Describing the function here
 * @param {type} normalVariable A normal variable
 * @param {type1 | type2} multiTypeVariable A variable with multiple expected types
 * @param {type} [variableWithDefaultValue="value"] An optional variable that has a default value in case of being absent when calling the function 
 * @param {type} [optionalVariable] An optional variable
 * @returns {type} description
*/
const functionName = (normalVariable, multiTypeVariable, variableWithDefaultValue, optionalVariable) => {
    doSomeThing();
}

Concernant les fonctions serveur avec les paramètres req et res, il n'est pas nécessaire de décrire les paramètres de requête ; décrivez uniquement la réponse en utilisant la description @returns.

/**
 * Describing the function here
 * @returns description
 */
functionName = (req, res) => {
    doSomeThing();
}

En général, il n'est pas nécessaire de décrire les paramètres req, res, next, to et from.

Dans les fichiers HTML, utilisez pour séparer les différentes parties du code ; par conséquent, l'utilisateur peut facilement identifier chaque pièce.

Si vous écrivez des commentaires au milieu d'une ligne de code, utilisez /* */.

const calc_result = (firstNumber * secondNumber)/* Explain the reason for the multiplication */   thirdNumber;

Échancrure

Les espaces de fin sont interdits.
N'oubliez pas de toujours mettre des espaces autour des expressions, des opérateurs et des symboles, ainsi qu'après les virgules et les accolades, s'ils ne sont pas les derniers caractères de la ligne.
Les lignes vides ne sont autorisées (et obligatoires) qu'à la fin du fichier (tous les fichiers doivent se terminer par une ligne vide), après le dernier module importé, en séparant les balises Modèle, Script et Style, et entre les ensembles de règles CSS.
N'oubliez pas d'utiliser Tab pour l'indentation et Espace pour l'alignement.

Commande

• Ordre les variables des schémas mangouste et l'état Vue Reactive des composants par ordre alphabétique, mais pour le reste du temps, ordonne les lignes de la plus courte à la plus longue.
• Classez les méthodes de route dans l'ordre suivant : put, get, post et delete, chacune étant elle-même classée par ordre alphabétique et toutes les routes doivent être regroupées en fonction de leurs URL.

Conclure

Bien que ce ne soient évidemment pas les meilleurs conseils qui soient, je pense qu'ils offrent un point de départ solide pour toute personne intéressée à apprendre les principes du code propre.
De plus, même si le respect strict de ces règles peut sembler difficile au départ, cela devient beaucoup plus simple avec la pratique.

Il est essentiel de souligner la nécessité de s'en tenir aux lignes directrices du projet actuel lorsqu'on travaille sur une base de code à long terme, même si elles sont insuffisantes. Si vous envisagez sérieusement de revoir les lignes directrices du projet, réfléchissez aux modifications les plus bénéfiques et laissez-les être injectées progressivement dans le projet.

Crédit image de couverture : Photo de Luis Gomes de Pexels