Documentation en JavaScript : comment écrire un code qui parle de lui-même

Pourquoi la documentation n'est pas une corvée ennuyeuse, mais un super-pouvoir pour le développeur

Imaginez : vous ouvrez un projet JavaScript qui n'est pas le vôtre (ou le vôtre, vieux de trois mois). Les fichiers regorgent de fonctions fléchées, d'async/await et de déstructuration. Mais pourquoi cette fonction s'appelle transformData ? Que prend-elle en entrée ? Et surtout, à quoi sert-elle, si processArray existe déjà ?

Si vous vous êtes déjà surpris à penser : « Je ne me souviens pas de ce qui se passe ici », cet article est pour vous. La documentation en JavaScript, ce ne sont pas des paragraphes ennuyeux. C'est une question de respect pour vous-même et vos collègues. C'est une question de rapidité d'intégration dans un projet et de réduction du nombre de bugs. Dans cet article, nous allons passer en revue les meilleures pratiques de documentation du code JS : de JSDoc à la génération d'une documentation complète.

Documentation du code JavaScript : la philosophie du « code qui parle »

Avant d'écrire des commentaires, il est important de comprendre : le meilleur commentaire est celui qui n'est pas nécessaire. Le code idéal doit s'expliquer de lui-même. Comment y parvenir ?

Nommage des variables et des fonctions

Mauvais exemple :

// Mauvais\nconst x = 10; // qu'est-ce que x ?\nfunction d(a, b) { return a * b; } // que fait d ?\n

Bon exemple :

// Bon\nconst MAX_RETRY_COUNT = 10;\nfunction calculateDiscountedPrice(price, discountPercent) {\n  return price * (1 - discountPercent / 100);\n}\n

Utilisez des noms complets et explicites. Nommez les fonctions avec des verbes (getUser, validateEmail), les variables avec des noms (userList, isActive). C'est la base du code auto-documenté.

Quand les commentaires sont-ils vraiment nécessaires ?

\n
• Logique métier complexe : par exemple, le calcul d'impôts selon une formule non évidente.
\n
• Solution de contournement ou temporaire : marquez avec TODO ou FIXME.
\n
• Pourquoi cette approche a été choisie : il y avait des alternatives, mais celle-ci est optimale en termes de vitesse.
\n
• Description de l'API publique : pour que les autres développeurs sachent comment appeler votre fonction.
\n

JSDoc : le standard de documentation JavaScript

JSDoc est une syntaxe pour écrire la documentation directement dans le code, comprise par les éditeurs (VS Code, WebStorm) et les outils de génération. C'est un incontournable pour tout projet sérieux.

Annotation de base d'une fonction

/**\n * Calcule le coût total d'une commande en tenant compte de la remise et de la taxe.\n * @param {number} price - Prix de base du produit.\n * @param {number} discount - Remise en pourcentage (0-100).\n * @param {number} taxRate - Taux de taxe en pourcentage (0-100).\n * @returns {number} Coût total.\n */\nfunction calculateTotal(price, discount, taxRate) {\n  const discountedPrice = price * (1 - discount / 100);\n  return discountedPrice * (1 + taxRate / 100);\n}\n

Désormais, en survolant la fonction calculateTotal dans l'éditeur, vous verrez sa description, ses paramètres et sa valeur de retour. Magique !

Annotations pour les objets et les types

/**\n * @typedef {Object} User\n * @property {number} id - Identifiant unique.\n * @property {string} name - Nom de l'utilisateur.\n * @property {boolean} isActive - Le compte est-il actif.\n */\n\n/**\n * Obtient la liste des utilisateurs actifs.\n * @param {User[]} users - Tableau d'utilisateurs.\n * @returns {User[]} Tableau filtré.\n */\nfunction getActiveUsers(users) {\n  return users.filter(user => user.isActive);\n}\n

L'utilisation de @typedef permet de créer vos propres types, rendant le code lisible et sûr. C'est particulièrement utile dans les projets sans TypeScript.

Documentation des fonctions asynchrones

/**\n * Charge les données d'un utilisateur depuis le serveur.\n * @async\n * @param {number} userId - ID de l'utilisateur.\n * @returns {Prom