Les commentaires en TypeScript ne servent pas à “traduire” le code pour les débutants, mais à expliquer ce que le typage ne dit pas encore : une règle métier, une contrainte technique, un compromis ou une intention. Le terme typescript comment renvoie en pratique à une question très concrète : comment écrire des annotations utiles, lisibles et maintenables sans transformer le fichier en bloc de texte. Dans cet article, je passe en revue les formats de commentaires, les cas où ils apportent vraiment de la valeur, les erreurs à éviter et la bonne manière de documenter une API.
L’essentiel à retenir avant d’écrire des commentaires
- `//` sert aux notes courtes et locales, `/** ... */` aux commentaires de documentation.
- Un bon commentaire explique surtout le pourquoi, pas le code déjà visible.
- Si une remarque peut être remplacée par un meilleur nom de fonction ou une extraction de logique, je préfère refactorer.
- `@ts-expect-error` est plus sûr que `@ts-ignore` quand on accepte volontairement une erreur de typage.
- Les commentaires d’API gagnent à suivre JSDoc ou TSDoc pour rester exploitables par l’éditeur et les outils de documentation.
- Un commentaire utile vieillit bien ; un commentaire vague devient vite faux.
Pourquoi commenter en TypeScript reste utile même avec les types
Le typage réduit déjà énormément le bruit, et c’est précisément pour cela qu’il faut être plus exigeant avec les commentaires restants. Si TypeScript indique qu’une variable est un string ou qu’une fonction attend un number, inutile de répéter l’évidence. En revanche, le typage ne raconte pas toujours la logique métier, les exceptions de performance, la raison d’un contournement ou la contrainte d’un service externe.
J’aime garder une règle simple : je commente ce que le code ne peut pas exprimer seul. Cela peut être une hypothèse cachée, une valeur magique choisie pour une bonne raison, une décision de sécurité, ou un ordre d’exécution volontaire. Dans une application web, c’est souvent là que les bugs naissent quand personne n’explique le “pourquoi”.
Autrement dit, les commentaires servent surtout à préserver le contexte humain. Et pour choisir la bonne forme, il faut d’abord distinguer les formats disponibles.
Les formats de commentaires à connaître
TypeScript reprend la syntaxe de JavaScript, donc il n’invente pas de nouveaux symboles. On retrouve trois formes principales, avec des usages différents selon le contexte. Dans beaucoup d’équipes, je conseille de réserver le bloc narratif aux rares cas où il apporte une vraie lisibilité, car un commentaire trop long finit souvent par ressembler à un mini paragraphe collé au code.
| Format | Usage recommandé | Point fort | Limite fréquente |
|---|---|---|---|
// |
Note courte, explication locale, rappel d’intention | Rapide à lire et à maintenir | Devient pénible si on l’utilise pour tout raconter |
/* ... */ |
Bloc de commentaire ponctuel, note temporaire, désactivation encadrée | Compact pour une remarque isolée | Peut vite devenir lourd si le texte est long |
/** ... */ |
Documentation de fonction, classe, module ou API publique | Lisible par les IDE et les générateurs de docs | Surdimensionné pour du code interne très local |
Dans le guide TypeScript de Google, on voit aussi une préférence pratique pour plusieurs lignes // plutôt qu’un long /* ... */ narratif quand il s’agit simplement d’expliquer quelques lignes. Ce n’est pas une loi universelle, mais c’est une bonne boussole pour éviter les pavés inutiles.
// Calcule le montant TTC en appliquant la TVA française
const totalTtc = prixHt * 1.2;
/**
* Retourne le libellé d'une commande.
* @param id - Identifiant interne de la commande
* @returns Libellé affichable par l'interface
*/
export function getOrderLabel(id: string): string {
return `Commande ${id}`;
}Une fois le format choisi, la vraie question devient plus intéressante : qu’est-ce qui mérite réellement d’être écrit ?
Écrire un commentaire utile sans alourdir le code
Le meilleur commentaire ne décrit pas ce que fait une ligne, il explique pourquoi cette ligne existe. Si le code est déjà clair, je n’ajoute rien. Si la logique est discrète ou si elle dépend d’une règle métier, alors je commente. Cette différence change tout, parce qu’un commentaire utile reste pertinent après un refactor alors qu’un commentaire descriptif se périme très vite.
// Mauvais : répète simplement le code
const prixAvecTva = prixHt * 1.2;
// Meilleur : explique la règle métier
// En France, on applique 20 % de TVA sur ce type de prestation
const prixAvecTva = prixHt * 1.2;Je m’en sers surtout dans ces cas précis :
- quand une valeur semble arbitraire mais correspond à une règle produit ou juridique ;
- quand un contournement technique évite un bug connu ou une limitation d’API ;
- quand un algorithme est correct, mais pas intuitif au premier regard ;
- quand une branche de code traite un cas limite rare mais critique ;
- quand un effet de bord n’est pas visible dans le nom de la fonction.
À l’inverse, je supprime sans hésiter les commentaires qui reformulent le code, ceux qui expliquent une variable déjà nommée correctement, ou ceux qui répètent une évidence du type “incrémente le compteur”. Si le commentaire ne donne pas une information supplémentaire, il prend juste de la place mentale. C’est précisément pour cette raison que la documentation d’API demande une approche un peu différente.
Documenter une API avec JSDoc et TSDoc
Pour les fonctions publiques, les classes ou les modules partagés, /** ... */ prend tout son sens. C’est la zone de JSDoc et, de plus en plus, de TSDoc : une manière structurée d’écrire des commentaires que les outils peuvent comprendre. Là, je ne parle plus d’une remarque locale, mais d’une documentation qui aide l’éditeur, l’équipe et parfois la génération automatique de références techniques.
Les balises les plus utiles au quotidien sont simples :
-
@parampour décrire un paramètre non évident ; -
@returnspour préciser ce que renvoie la fonction ; -
@examplepour montrer un usage réel ; -
@deprecatedpour signaler une API à remplacer ; -
@seepour renvoyer vers une autre fonction, une classe ou une règle associée.
/**
* Calcule le total TTC à partir du montant HT.
* @param amountHt - Montant hors taxes
* @param vatRate - Taux de TVA, par exemple 0.2
* @returns Montant TTC arrondi à deux décimales
* @example
* calculateTtc(100, 0.2) // 120
*/
export function calculateTtc(amountHt: number, vatRate: number): number {
return Math.round(amountHt * (1 + vatRate) * 100) / 100;
}
Ce type de commentaire a un vrai intérêt quand une API est utilisée par plusieurs personnes ou par plusieurs services. L’important, c’est la cohérence : si tu commences à documenter une fonction publique, fais-le proprement et régulièrement, sinon la doc devient incomplète et donc peu fiable. Et comme tout document vivant, elle doit aussi gérer les cas où l’on force la main au compilateur.
Les commentaires qui posent problème
Il existe une catégorie de commentaires que je traite avec prudence : ceux qui désactivent une erreur TypeScript, ou ceux qui masquent un problème au lieu de le résoudre. Les plus connus sont @ts-ignore et @ts-expect-error. Le premier supprime l’erreur sur la ligne suivante sans rien vérifier ; le second est plus strict, car il échoue si l’erreur disparaît. En pratique, je préfère @ts-expect-error dès que le cas est volontaire et temporaire.
// @ts-expect-error - La librairie externe renvoie encore un type incomplet
const value = legacyClient.fetchUser(userId);
// @ts-ignore
const value2 = legacyClient.fetchUser(userId);La différence est importante : @ts-expect-error garde une forme de contrôle qualité, alors que @ts-ignore peut rester en place longtemps sans alerte. Dans un codebase sérieux, je réserve donc @ts-ignore aux migrations, aux blocages transitoires ou aux cas où je sais précisément pourquoi le compilateur a tort, et où je veux revenir dessus rapidement.
Je mets aussi dans cette zone les commentaires TODO et FIXME. Ils sont utiles, mais seulement s’ils sont actionnables. Un TODO sans responsable, sans contexte et sans ticket finit par devenir un post-it numérique oublié. Si je le garde, j’essaie de préciser le motif, le point de blocage ou la prochaine étape.
// TODO: retirer ce contournement quand l'API v2 sera déployée
// FIXME: gérer les réponses vides du service de paiement
Le fil conducteur est simple : un commentaire ne doit pas masquer une dette technique, il doit la rendre visible. C’est aussi pour cela qu’il faut relire ses commentaires avec une grille très concrète avant de les conserver.
Le filtre que j’applique avant de garder un commentaire
Avant de laisser un commentaire dans un projet TypeScript, je me pose toujours les mêmes questions. Si je n’ai pas de réponse solide à au moins une d’entre elles, je l’enlève ou je refactorise le code à la place.
- Est-ce que le code est déjà assez clair sans cette note ?
- Est-ce que le commentaire explique une contrainte, une décision ou une exception réelle ?
- Est-ce qu’il restera vrai après un changement raisonnable du code ?
- Est-ce qu’une fonction plus petite, un nom plus précis ou une constante mieux nommée ferait le même travail ?
- Est-ce que ce commentaire aide vraiment une autre personne dans 3 mois, ou seulement moi aujourd’hui ?
En pratique, si j’ai besoin de plus de 3 lignes pour expliquer une logique locale, je revois d’abord la structure du code. Souvent, le meilleur commentaire est celui qu’on n’a pas besoin d’écrire parce que la fonction, le nom de variable ou la séparation des responsabilités fait déjà le travail.
La bonne habitude, au fond, est assez sobre : commenter moins, mais mieux. Quand un commentaire capture une décision importante, une règle métier ou une exception technique, il mérite sa place. Sinon, je préfère laisser le code parler par lui-même.
