commenti in php

Aggiungere commenti in PHP: a singola linea e multilinea

di

Quando si scrive un programma, è fondamentale aggiungere commenti. I commenti possono essere aggiunti all’inizio di un pezzo di codice per descriverlo genericamente e tra ogni singolo step per descrivere ogni singola parte di quel codice.

Commentare un codice serve:

  • a noi sviluppatori per ricordarci a distanza di tempo cosa fa un programma o una parte specifica di codice
  • a permettere ad altri sviluppatori di comprendere meglio il nostro codice

PHP permette di aggiungere commenti nelle seguenti modalità:

  • a singola linea
  • multilinea

Commenti a singola linea

Per poter scrivere un commento a linea singola posso utilizzare due simboli diversi:

  • il cancelletto “#“
  • oppure i due slash “//“

Ecco un esempio rapido:

<?php

# Commento in PHP con il cancelletto
$nome = "Michele";
echo "Mi chiamo " . $nome;

// Commento in PHP con i due slash
$annoCorrente = "2023";
echo "Siamo nell'anno " . $annoCorrente;

?>

Posso utilizzare i commenti a linea singola anche dopo una dichiarazione (statement) o riga di codice rimanendo sulla stessa riga in questo modo:

<?php

$nome = "Michele"; # Definisco una variabile per il nome
$professione = "sviluppatore web"; // Definisco una variabile per il cognome

echo "Mi chiamo " . $nome . " e faccio lo " . $professione; // Compongo la frase con le variabili

Non c’è bisogno di mettere il punto e virgola “;” dopo un commento.

PHP riconoscerà ogni stringa dopo il cancelletto “#” e dopo i doppi slash “//” e prenderà quella riga o quella parte di riga come commento e NON la eseguirà come codice.

Commenti multilinea

I commenti multilinea, come dice il nome stesso, permettono di scrivere un commento di un programma su più righe.

Quindi permettono di avere più spazio e una migliore organizzazione nella scrittura di un commento se questo non può rimanere su una sola riga.

Per scrivere un commento multilinea bisogna aprire il commento con i segni slash e asterisco “/*” e chiuderlo con asterisco e lo slash “*/“:

<?php
/*
    Questo è un commento multilinea in PHP
    In questo modo posso scrivere commenti più lunghi...
    Più descrittivi...

    In modo da rendere più comprensibile il mio programma agli altri e al me del futuro!
*/

Quindi, quando hai bisogno di scrivere commenti più corposi e su più righe utilizzerai questo metodo.

Potrebbe capitarti che in vari IDE (ambiente di sviluppo integrato o code editor), come visual studio code, quando avvierai un codice multilinea ti verrà automaticamente generato questo:

<?php

/** */

?>

E poi andando a capo più volte avrai questo:

<?php
/**
 * 
 * 
 * 
 * 
 */

?>

Questo è perfettamente normale ed è sempre un commento multilinea. Gli asterischi in più danno una sorta di senso di ordine al commento:

<?php
/**
 *  Commento multilinea
 *  Con asterischi in più
 *  ...
 *  Ma si tratta della stessa cosa!
 */

?>

Altri esempi di commenti in PHP

Puoi utilizzare i commenti per mettere “fuori uso” parti di codice nella stessa linea, ad esempio:

echo 2 + 5 + 7;     // Risultato 14

Togliamo dalla somma “+5”:

echo 2 /* + 5 */ + 7;    // Risultato 9

Oppure puoi commentare una linea di tante righe di codice di un programma più complesso:

Queste pratiche sono molto utili per fare bug fixing e testing del codice.

Puoi inserire commenti anche all’interno di:

  • blocchi if, if-else, if-else if
  • case-switch
  • loop (for, foreach, while, do while)
  • funzioni
  • classi

Ecco un esempio di utilizzo di commenti in una classe in PHP:

<?php

/**
 * Commenta le tue classi per rendere comprensibile la loro funzione
 */

// Realizziamo una nuova classe
class Profilo {

    // Variabile per salvare il nome
    private string $nome = '';

    // Variabile per salvare il cognome
    private string $cognome = '';

    // Variabile per l'età
    private int $eta = 0;

    // Variabile per la professione
    private string $professione = '';

    // La funzione construct della nostra classe per inserire i dati
    public function __construct(string $nome, string $cognome, int $eta, string $professione) {
    
        // Inseriamo tutti i dati disponibili nelle proprietà della classe
        $this->nome = $nome;
        $this->cognome = $cognome;
        $this->eta = $eta;
        $this->professione = $professione;

    }  

    /**
     * Funzione per ottenere il nome
     * Ritorna una stringa
     */
    public function get_firstname() : string {
        return $this->nome;
    }

    // Funzione per ottenere il cognome
    public function get_lastname() : string {
        return $this->cognome;
    }

    // Funzione per ottenere l'età
    public function get_age() : int {
        return $this->eta;
    }

    // Funzione per ottenere l'occupazione
    public function get_employment() : string {
        return $this->professione;
    }
}

// Istanziamo una classe e inseriamo i dati
$mio_profilo = new Profilo('Michele', 'Mincone', 21, 'sviluppatore web');

// Prendiamo nome e cognome
echo $mio_profilo->get_firstname();

echo "<br>"; // andiamo a capo...

echo $mio_profilo->get_lastname();

?>

Ed ecco un altro esempio di utilizzo di commenti in un blocco if-else:

<?php

$eta = 25;

// Prepariamo il blocco if-else
if ($eta >= 18) {

    // Maggiorenne
    echo "Sei maggiorenne";

} else {

    // Minorenne
    echo "Sei minorenne!!!";

}

?>

Scrivi commenti brevi, semplici e descrittivi

I commenti sono fondamentali per permettere a te stesso di ritornare sul codice in futuro e comprenderlo al meglio e nel minor tempo possibile.

Serviranno anche ad altri programmatori che leggeranno il tuo codice permettendogli una comprensione migliore.

Quindi l’utilizzo dei commenti dovrebbe essere orientato nel seguente modo:

  • Utilizza commenti multilinea all’inizio del tuo programma PHP e descrivi cosa fa quel file nello specifico. Ogni singolo file PHP dovrebbe avere un commento all’inizio che descriva cosa fa quel file, includendo tutte le dinamiche.
  • Utilizza i commenti multilinea per descrivere una funzione o altri pezzi di codice lunghi che effettuano operazioni di complessità media o elevata.
  • Utilizza i commenti a singola linea per descrivere singole operazioni che potrebbero essere difficili da ricordare nel futuro o se ritieni che sia necessario.

Questi sono casi generici e ovviamente ci sono tante eccezioni perché ogni programma è diverso dall’altro.

Ma se si ritiene che un pezzo di codice debba essere descritto ecco che lasciare un commento è d’obbligo.

Scrivi commenti semplici da leggere, quindi evita papiri disordinati che non arrivano al punto, che descrivano la funzione di quel codice includendo tutte le dinamiche.