Commenti in TypeScript: JSDoc, @ts-ignore e @ts-expect-error

I commenti TypeScript sono commenti JavaScript: // per il resto di una riga e /* */ per un blocco. Un commento a blocco che inizia con /** è un commento di documentazione (JSDoc), che gli editor mostrano quando passi il mouse sull'elemento documentato. In più, TypeScript legge alcuni commenti speciali che cambiano il modo in cui il compilatore controlla il tuo codice.

// A single-line comment runs to the end of the line.

/*
  A block comment can span
  several lines.
*/

/**
 * Converts a temperature from Celsius to Fahrenheit.
 * @param celsius Degrees Celsius.
 * @returns Degrees Fahrenheit.
 */
function toFahrenheit(celsius: number): number {
    return (celsius * 9) / 5 + 32; // a comment after code
}

console.log(toFahrenheit(100)); /* inline block comment */ // 212

Output:

212

I commenti non influiscono sul programma. Non influiscono nemmeno sul controllo dei tipi, tranne i commenti direttiva trattati più sotto.

Commenti su una riga e a blocco

// commenta tutto ciò che segue sulla riga, ed è anche il modo rapido per disattivare una riga di codice. /* */ può stare in mezzo a una riga o coprire molte righe.

I commenti a blocco non si annidano. Il primo */ chiude il commento, quindi racchiudere codice che contiene già un commento a blocco lo rompe:

/* outer comment /* inner comment */ this text is now code */

Il compilatore prova allora a leggere this text is now code */ come codice e segnala un errore di sintassi. Per commentare una zona che contiene commenti a blocco, usa // su ogni riga; la maggior parte degli editor lo fa con Ctrl+/ (Cmd+/ su macOS).

Commenti di documentazione JSDoc

Un commento /** ... */ subito prima di una funzione, classe, metodo, proprietà, interfaccia o variabile la documenta. Gli editor mostrano il suo testo nel tooltip al passaggio del mouse e nell'autocompletamento, e i generatori di documentazione come TypeDoc lo trasformano in pagine di riferimento. TSDoc, uno standard per questi commenti nel codice TypeScript avviato da Microsoft, usa la stessa sintassi per i tag più comuni:

In un file .ts, non ripetere i tipi in JSDoc. I tipi sono le annotazioni nel codice, e lì i tag di tipo JSDoc vengono ignorati: /** @type {string} */ const v: number = 5; compila senza lamentele perché conta solo : number.

interface Account {
    /** Balance in cents, to avoid floating-point rounding. */
    balance: number;
}

/**
 * Moves money between two accounts.
 * @param from The account to take the money from.
 * @param to The account that receives it.
 * @param cents Amount in cents. Must not exceed `from.balance`.
 * @throws {RangeError} If the balance is too low.
 */
function transfer(from: Account, to: Account, cents: number): void {
    if (cents > from.balance) {
        throw new RangeError("insufficient funds");
    }
    from.balance -= cents;
    to.balance += cents;
}

const a: Account = { balance: 5000 };
const b: Account = { balance: 0 };
transfer(a, b, 1250);
console.log(a.balance, b.balance); // 3750 1250

In un editor, passando il mouse su transfer o balance in qualsiasi punto del progetto vedi queste descrizioni.

Marcare il codice come deprecato

@deprecated non causa un errore di compilazione. Dice agli editor di mostrare ogni uso della funzione deprecata barrato, con il motivo al passaggio del mouse, ed è il modo gentile per indirizzare chi chiama verso un sostituto:

/** @deprecated Use {@link formatPrice} instead. It ignores the currency. */
function price(cents: number): string {
    return "$" + (cents / 100).toFixed(2);
}

function formatPrice(cents: number, currency: string): string {
    return `${(cents / 100).toFixed(2)} ${currency}`;
}

console.log(price(1999));              // still compiles and runs
console.log(formatPrice(1999, "EUR"));

Output:

$19.99
19.99 EUR

@ts-expect-error e @ts-ignore

Questi due commenti zittiscono gli errori di tipo sulla riga che segue. A volte è la scelta giusta: un test che verifica come una funzione gestisce un input sbagliato a runtime, o una lacuna nota nei tipi di una libreria.

function shout(text: string): string {
    return text.toUpperCase();
}

try {
    // @ts-expect-error: testing what happens when JavaScript callers pass a number
    shout(42);
} catch (e) {
    if (e instanceof Error) {
        console.log("runtime error:", e.message);
    }
}

Output:

runtime error: text.toUpperCase is not a function

Senza il commento, shout(42) è un errore di compilazione (TS2345). Con il commento, il file compila e la chiamata arriva al runtime, che è lo scopo di questo test.

La differenza tra le due direttive emerge quando l'errore sparisce. @ts-expect-error pretende che ci sia un errore da sopprimere, quindi un commento obsoleto diventa esso stesso un errore:

// This does not compile: the line below has no type error to suppress.
function shout(text: string): string {
    return text.toUpperCase();
}

// @ts-expect-error
console.log(shout("fixed"));

index.ts(6,1): error TS2578: Unused '@ts-expect-error' directive.

// @ts-ignore nello stesso punto resta muto, sia mentre l'errore esiste sia dopo che è sparito. Ecco perché @ts-expect-error è la scelta predefinita migliore: quando qualcuno sistema i tipi, il compilatore ti dice che la soppressione può essere tolta. Aggiungi sempre un motivo dopo la direttiva, come nell'esempio sopra, così chi legge dopo sa perché è lì.

Entrambe coprono solo la riga successiva e tutti gli errori su di essa. Per aggirare i controlli su un intero valore, un esplicito as unknown as T o un controllo a runtime è di solito più chiaro di un commento di soppressione.

@ts-nocheck e @ts-check

// @ts-nocheck in cima a un file disattiva il controllo dei tipi per tutto quel file. Deve venire per primo, prima di qualsiasi codice: messo più in basso viene ignorato e gli errori compaiono comunque.

// @ts-nocheck
const n: number = "not a number"; // no error reported

È utile durante la migrazione di un grande codebase JavaScript, e un campanello d'allarme in qualsiasi altro caso.

// @ts-check fa l'opposto in un file JavaScript: attiva il controllo dei tipi per quel file .js, usando l'inferenza e i tipi JSDoc, anche quando checkJs è disattivato in tsconfig.json (il file deve comunque far parte del progetto, tramite allowJs):

// @ts-check

/**
 * @param {number} cents
 * @returns {string}
 */
function formatCents(cents) {
    return (cents / 100).toFixed(2);
}

formatCents("12"); // error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Nei file JavaScript i tag JSDoc sono i tipi, ed è così che molti progetti ottengono il controllo dei tipi senza convertire i file in .ts.

Direttive triple-slash

Un commento della forma /// <reference ... /> proprio in cima a un file è una direttiva per il compilatore:

/// <reference types="node" />
/// <reference lib="es2023.array" />
/// <reference path="./globals.d.ts" />

• types="node" aggiunge un pacchetto @types al programma, come elencarlo in "types" in tsconfig.json.
• lib="..." aggiunge una libreria predefinita al programma, come l'opzione lib.
• path="..." include un altro file, usato soprattutto dentro i file .d.ts.

Nel codice applicativo, le istruzioni import e le impostazioni di tsconfig.json sostituiscono quasi ogni uso; queste direttive le incontri soprattutto nei file di dichiarazione e nel codice generato come il vite-env.d.ts di Vite. Come rapida dimostrazione, lib rende disponibile in questo file un metodo degli array più recente:

/// <reference lib="es2023.array" />

const scores = [72, 95, 88];
const ranked = scores.toSorted((a, b) => b - a); // ES2023, copies instead of sorting in place

console.log(ranked); // [ 95, 88, 72 ]
console.log(scores); // [ 72, 95, 88 ]

Commenti nell'output compilato

tsc mantiene i commenti nel JavaScript che scrive. Imposta "removeComments": true per eliminarli; i commenti che iniziano con /*! sopravvivono anche in quel caso, ed è la convenzione per le intestazioni di licenza:

/*! MyLib v1.2.0 | MIT License */

I commenti JSDoc vengono copiati anche nei file .d.ts quando declaration è attivo, così chi usa una libreria vede le descrizioni nel proprio editor.