TOC

Comment écrire des commentaires en JavaScript

introduction

En programmation, notre première considération est généralement la machine - comment l'ordinateur lit et interprète le code que nous écrivons. Cependant, il est tout aussi important de prendre en compte les personnes qui liront et travailleront avec le code. Que vous travailliez seul ou en équipe, vous devrez apprendre à commenter et à structurer correctement votre code pour des lecteurs humains.

Les commentaires sont des annotations dans le code source d'un programme qui sont ignorées par l'interpréteur et n'ont donc aucun effet sur la sortie réelle du code. Les commentaires peuvent être extrêmement utiles pour expliquer l'intention de ce que votre code est ou devrait faire.

En tant que développeur, il peut être frustrant d’explorer du code écrit par une autre personne qui n’a pas été commentée correctement. Il est également très facile d’oublier ce que votre propre code signifiait lorsque vous n’êtes plus plongé dans le contexte d’un programme. Le fait de commenter votre code dès le début renforcera les bonnes habitudes de programmation tout au long de votre carrière pour éviter ces problèmes plus tard.

Examinons rapidement les deux types de syntaxe de commentaire JavaScript.

Les commentaires deSingle-line sont écrits avec deux barres obliques (//): 

// This is a comment

Tous les caractères suivant immédiatement la syntaxe// jusqu'à la fin de la ligne seront ignorés par JavaScript.

Les commentaires deBlock, parfois appelés commentaires demutli-line, sont écrits avec des balises d'ouverture (/*) et des balises de fermeture (*/). Si vous connaissez le langage CSS, vous connaissez déjà les commentaires au niveau des blocs. 

/* This is
a comment */

Tout ce qui se trouve entre les balises d'ouverture et de fermeture dans le bloc de code ci-dessus sera ignoré.

Les commentaires sur une ligne ou sur plusieurs lignes sont écrits au-dessus du code qu'ils sont censés expliquer, comme le montre cet exemple «Hello, World!»:

hello.js

// Print "Hello, World!" to the console
console.log("Hello, World!");

Lorsque vous écrivez des commentaires, indentez-les au même niveau que le code immédiatement inférieur à eux:

ocean.js

// Initialize a function
function alphabetizeOceans() {
    // Define oceans variable as a list of strings
    const oceans = ["Pacific", "Atlantic", "Indian", "Antarctic", "Arctic"];

    // Print alphabetized array to the console
    console.log(oceans.sort());
}

Notez que les commentaires font tout autant partie du code que le programme lui-même. Les commentaires obsolètes peuvent être plus préjudiciables que l'absence de commentaire du tout, alors n'oubliez pas de maintenir et de mettre à jour les commentaires régulièrement, avec le reste.

Les commentaires sur une seule ligne sont appelésinline comments lorsqu'ils apparaissent à la fin d'une ligne de code. 

let x = 99;    // assign numerical value to x
let y = x + 2; // assign the sum of x + 2 to y

Les commentaires en ligne peuvent être utilisés pour des annotations rapides sur de petits extraits de contenu spécifiques. Comme le commentaire ne doit porter que sur la ligne exacte sur laquelle il est écrit, il s’agit du type de commentaire le plus évident.

N'oubliez pas qu'il n'y a aucun moyen de terminer un commentaire d'une seule ligne sur une ligne, alors assurez-vous de ne pas mettre de code après la syntaxe//, comme le montre l'exemple ci-dessous.

broken.js

for (let i = 0; i === 10; i++) // for loop that runs ten times {
    // Running this code results in a syntax error
}

Bien que les commentaires en ligne puissent être utiles, ils doivent être utilisés avec parcimonie - le code couvert par une abondance de commentaires en ligne deviendra rapidement désordonné et donc difficile à lire.

Les commentaires au niveau du bloc, ou les commentaires sur plusieurs lignes, sont des annotations longues utilisées pour introduire et expliquer une section de code. Souvent, ces types de commentaires sont placés en haut d'un fichier ou avant un bloc de code particulièrement complexe.

greet.js

/* Initialize and invoke a the greetUser function
to assign user's name to a constant and print out
a greeting. */

function greetUser() {
    const name = prompt("What is your name?");
    console.log("Hello ," + name + "! How are you?");
}

greetUser();

Vous pouvez aussi parfois voir une version légèrement modifiée de la syntaxe des commentaires de bloc, qui commence par/** et inclut des astérisques sur le côté gauche du bloc de commentaires.

sea.js

/**
 * Initialize constant with an array of strings.
 * Loop through each item in the array and print
 * it to the console.
 */

const seaCreatures = ["Shark", "Fish", "Octopus"];

for (const seaCreature of seaCreatures) {
  console.log(seaCreature);
}

Parfois, ce type de commentaire comprend également des détails sur le fichier de programmation, notamment le nom du script, sa version et son auteur.

Si vous êtes un débutant en JavaScript, vous pouvez écrire autant que nécessaire pour apprendre et comprendre le code que vous écrivez. Au fur et à mesure que vous progresserez en tant que développeur JavaScript, vous chercherez à répondre à l'intention, ou auxwhy derrière le code, par opposition auxhow ouwhat.

Les commentaires peuvent également être utilisés pour empêcher rapidement et facilement l'exécution de code à des fins de test et de débogage. Ceci est appelé «code de commentaire».

Si le code que vous avez écrit contient une erreur, le commentaire en les empêchant de s'exécuter, peut être utile pour identifier la source du problème. Vous pouvez également l'utiliser pour basculer entre les codes afin de tester différents résultats.

math.js

// Function to add two numbers
function addTwoNumbers(x, y) {
  let sum = x + y;
  return sum;
}

// Function to multiply two numbers
function multiplyTwoNumbers(x, y) {
  let product = x * y;
  return product;
}

/* In this example, we're commenting out the addTwoNumbers
function, therefore preventing it from executing. Only the
multiplyTwoNumbers function will run */

// addTwoNumbers(3, 5);
multiplyTwoNumbers(5, 9);

Les commentaires sur une seule ligne et les commentaires sur les blocs peuvent être utilisés pour commenter le code, en fonction de la taille de la section en cours de basculement.

[.note] #Note: La mise en commentaire du code ne doit être effectuée qu'à des fins de test. Ne laissez pas d'extraits de code commenté dans votre script final.
#

Lorsque vous définissez la logique d'un programme, la mise en commentaire de code peut s'avérer utile pour déterminer l'emplacement des bogues ou évaluer les lignes de code offrant le plus d'utilité.

Conclusion

Le code JavaScript est interprété par l'ordinateur, mais sera toujours lu par d'autres programmeurs, y compris votre futur. Prendre le temps de laisser des annotations correctes sur des sections de code compliquées rapportera des dividendes à l'avenir, ce qui facilitera pour vous et vos collaborateurs la compréhension de l'intention du code que vous avez écrit.

Related