sabato 22 febbraio 2025

TypeScript l’uso dei commenti anche in Angular

Introduzione

In questo articolo vedremo l’uso dei commenti nella tecnologia Angular e nel linguaggio TypeScript, che può avvenire in vari modi.  Nella creazione delle applicazioni, i commenti ricoprono un aspetto molto importante, da una parte per la leggibilità del codice e dall’altra nel caso che si vuole evitare o annotare alcuni frammenti di codice.

In questo articolo vedremo i vari utilizzi dei commenti da utilizzare nelle applicazioni Angular, con il linguaggio di programmazione TypeScript.

I commenti sono una parte presente nel codice che non viene eseguita ma permette al programmatore di fornire informazioni sulla leggibilità di codice oppure annotare alcuni frammenti di codice.


Stesura del codice

Dopo aver creato un nuovo progetto oppure utilizzare uno già esistente nel quale fare i test, utilizziamo una pagina semplice html   ed un file .ts con poco codice in modo da fare le prove.

L’ambiente di sviluppo che utilizzeremo è Visual Studio Code, va bene qualsiasi versione.

I Commenti

Nella maggior parte dei casi, i programmatori usano i commenti quelli standard, quelli più usati di frequente.

Di seguito si riporta un frammento di codice dei commenti lato html e Typescript

HTML

 <div>

  <!-- Commento di test test -->

</div>

TypeScript

  //Evento di apertura pagina

  ngOnInit(): void {

 

 

 

Figura 1 – Il commento lato HTML
Figura 1 – Il commento lato HTML

Figura 2 – Il commento lato TypeScript
Figura 2 – Il commento lato TypeScript


Come si è visto nel precedente frammento di codice, i commenti sono riportati nell’ambiente di sviluppo Visual Studio Code, di colore verde, salvo che non si è cambiata l’impostazione de default.

Per la parte riguardante html, il commento viene fatto tramite la serie iniziale di simboli <! -  - e nella parte finale del testo che si vuole commentare i seguenti simboli  --> 

Tutto ciò che viene racchiuso in questi simboli è commentato.

Mentre per quanto riguarda il linguaggio di programmazione TypeScript, il commento avviene tramite l’uso del simbolo //

Commenti su più righe parte TypeScript

Nel caso che vogliamo commentare una parte di codice su più righe in ambito del linguaggio TypeScript, dobbiamo utilizzare altri simboli.

Come si vede dal frammento di codice qui di seguito, tutto il testo compreso nei simboli  /* e */ viene commentato.

TypeScript
/*
    this.nominativi.push(new Nominativo('Emanuele', 'Mattei', new Date('12/12/1974')));
    this.nominativi.push(new Nominativo('Luigi', 'Cristaldi', new Date('12/12/1984')));
    this.nominativi.push(new Nominativo('Luca', 'Rossi', new Date('12/12/1954')));
    this.nominativi.push(new Nominativo('Max', 'Bianchi', new Date('12/12/1994')));
*/

/*

    this.nominativi.push(new Nominativo('Emanuele', 'Mattei', new Date('12/12/1974')));

    this.nominativi.push(new Nominativo('Luigi', 'Cristaldi', new Date('12/12/1984')));

    this.nominativi.push(new Nominativo('Luca', 'Rossi', new Date('12/12/1954')));

    this.nominativi.push(new Nominativo('Max', 'Bianchi', new Date('12/12/1994')));

*/

 

Figura 3 – I commenti su più righe in ambito TypeScript
Figura 3 – I commenti su più righe in ambito TypeScript


Commenti descrittivi per le funzioni

Quando si creano funzioni, è sempre cosa buona scrivere una breve descrizione per spiegare la funzione, se questa funzione viene utilizzata al di fuori della classe, per esempio come metodo, diviene importante fornire una breve descrizione della funzione stesssa.

Quando digitiamo il nome della funzione o del metodo, viene visualizzato un tooltiptext, un piccolo pannelli temporale con le informazioni che abbiamo impostato.

Di seguito si riporta il commento che fornirà una descrizione alla funzione quando si digiterà o si posizionerà il mouse sul nome della funzione.


TypeScript:


/**

      Esegue la funzione MiaFunzione

    altro testo

    testo

     */

  MiaFunzione() : void{

 

  }


Nel momento in cui si posizionerà il puntatore del mouse sopra il nome della funzione, che stiamo utilizzando in altra parte del codice o in un altro file, verrà visualizzata la finestra informativa come riportato nella figura qui di seguito.  


Figura 4 – La finestra informativa della funzione
Figura 4 – La finestra informativa della funzione

Per ottenere questo risultato, occorre utilizzare i simboli /**  */ con una descrizione su più righe.

Per quanto riguarda la descrizione delle funzioni, se vogliamo applicare altra formattazione al testo descrittivo, possiamo fare in modo che una parte è più evidenziata dell’altra, con formattazione più grande e grassetto, il tutto come mostrato in figura 5.

Figura 5 – La finestra informativa della funzione con particolare formattazione
Figura 5 – La finestra informativa della funzione con particolare formattazione

Per ottenere questo risultato, con una parte formattata in carattere più grande e grassetto, dobbiamo applicare alla funzione il seguente commento.


TypeScript:

   /**

     * Esegue la funzione MiaFunzione2

     * -

     * Altro testo

     */

  MiaFunzione2():void{



  }

 

Come si è visto dal precedente frammento di codice, la parte superiore del simbolo meno “-“ viene formattata con carattere più grande e grassetto, mentre la parte inferiore al simbolo del “-“ con formattazione standard.

Sempre nell’uso dei commenti, potrebbe tornare utile impostare alcune parole di tipo iperlink, ossia che al click aprono un sito internet del browser predefinito.

Per ottenere questo risultato dobbiamo mettere la parola o la frase tra parentesi quadrate e subito seguito tra parentesi tonde il sito che verrà aperto.

Si riporta il frammento di codice delle suddette operazioni.

TypeScript:

/**

 * Informazioni riguardante la funzione con uso del sito internet

 *   Questa è la parola [iprogrammatori](https://www.iprogrammatori.it)  che apre

 * un sito

 */

public NomeFunzione(){

 

return;

 

}

 

Il risultato sarà come riportato qui di seguito:

Figura 6 – La descrizione con una parola che al click apre il sito impostato.


Nel caso che si vuole inserire nella descrizione di una funzione o di altra parte di codice, un esempio di utilizzo, possiamo inserire nei commenti una formattazione che il codice TypeScript viene visualizzato come se fosse formattato con gli stessi colori dell’ambiente di sviluppo.

Per riportare l’esempio di utilizzo formattato con la stessa impostazione dell’ambiente di sviluppo, tramite l’apertura del tag di tre singoli apici seguito dalla parola js, ed a conclusione della parte di esempio i tre singoli apici, tutto quello compreso in questi due tag sarà formattato come frammento di codice TypeScript.

Di seguito si riporta un esempio di utilizzo di tale utilizzo


TypeScript:

/**

 * Informazioni riguardante la funzione con uso del sito internet

 *   Questa è la parola [iprogrammatori](https://www.iprogrammatori.it)  che apre

 * un sito

* ```js

* //Esempio di codice

* numero: number = 7;

* console.log('numero ' + numero);

 * ```

 */

 Di seguito si riporta l’immagine di come verrà visualizzato .


Figura 7 – La visualizzazione del codice  con la stessa formattazione dell’ambiente di sviluppo
Figura 7 – La visualizzazione del codice  con la stessa formattazione dell’ambiente di sviluppo


Se desideriamo visualizzare nella descrizione del codice, una parola in grassetto o in corsivo, nei commenti dovremmo utilizzare il simbolo del doppio asterisco (**) che all’interno di inizio doppio asterisco e fine doppio asterisco riporterà il testo in grassetto. Per formattarlo in maniera corsivo dovremmo racchiudere la parola tramite il simbolo trattino in basso “_”.

Si riporta un frammento di codice per formattare in grassetto ed in corsivo una parola.


TypeScript

/**

 * **Parola** formattata in maniera grassetto

 *

 * _Parola_ formattata in maniera corsivo

 */

public NomeFunzione2(){

 

  console.log("Numero: " + 6);

return;

 

}

 

Il risultato sarà come riportato nella figura 8.


Figura 8 – La formattazione in grassetto e corsivo delle due parole.
Figura 8 – La formattazione in grassetto e corsivo delle due parole.


Altra possibilità di formattare il testo nei commenti, in modo che viene visualizzato con aspetti particolari, è quella di creare un elenco puntato. Per ottenere questo risultato, occorre che le singole frasi siano precedute da doppi asterischi **.

Di seguito si riporta un frammento di codice di un elenco puntato con tre voci.

TypeScript

/**

 * Di seguito elenco puntato

 ** Primo Elenco

 ** Secondo Elenco

 ** terzo Elenco

 *

 */

public NomeFunzione2(){

 

  console.log("Numero: " + 6);

return;

 

}

 

Il risultato sarà come riportato nell’immagine 9.


Figura 9 – La visualizzazione del testo con l’elenco puntato.
Figura 9 – La visualizzazione del testo con l’elenco puntato.


Nella visualizzazione della descrizione, può tornare utile informare dei parametri che vengono passati ad una determinata funzione.

Nei commenti, tra le varie parole chiave che abbiamo a disposizione, possiamo definire i parametri ed il valore di ritorno di una funzione.

Di seguito si riporta un esempio che descrive due parametri e che ritorna un valore di tipo string.


TypeScript


 /**

  *

  * @param parametro - Primo parametro

  * @param   parametro2 - Secondo parametro

  * @returns Restituisce testo

  *

   */

public NomeFunzione3(parametro: string, parametro2: number){

 

return "";

}

 

La descrizione sarà visibile come in figura 10.

Figura 10 – La descrizione della funzione indicante i parametri ed il valore di ritorno
Figura 10 – La descrizione della funzione indicante i parametri ed il valore di ritorno



Conclusioni

L’articolo ha voluto fornire una panoramica sull’utilizzo dei commenti ed  una serie di esempi in vari ambiti.

I commenti sono una parte essenziale permettendo la leggibilità del codice ma soprattutto in quei contesti dove è presente un gruppo di sviluppo, che deve effettuare di volta in volta manutenzione o integrazione al proprio progetto.  I commenti non sono obbligatori ma è importante utilizzarli nella maniera corretta affinché si renda più leggibile il codice e soprattutto si migliora la manutenzione. 

Nessun commento: