Capire i Commenti PHP

I commenti sono note che lasci nel codice sorgente che PHP ignora durante l'esecuzione del programma. Esistono esclusivamente per gli esseri umani — per spiegare perché un pezzo di codice fa quello che fa, per lasciare promemoria o per disabilitare temporaneamente il codice durante il debug. Questa guida tratta ogni sintassi di commento supportata da PHP, quando usarne ciascuna e le pratiche che mantengono i commenti utili anziché rumore.

Questo capitolo presuppone che tu sappia già come scrivere PHP di base. In caso contrario, inizia prima con i capitoli Sintassi PHP e Variabili PHP.

Cosa sono i Commenti PHP?

Un commento è testo nel codice che il motore PHP non esegue. Quando PHP analizza un file, salta completamente i commenti — non influenzano mai l'output, le prestazioni o il comportamento. Servono come documentazione per chiunque legga il codice successivamente, incluso il tuo io futuro.

PHP supporta tre stili di commento, che rientrano in due gruppi:

• Commenti a riga singola, scritti con // o #.
• Commenti multi-riga (blocco), scritti con /* ... */.

PHP eredita gli stili // e /* */ da C e Java, e lo stile # dagli script di shell e da Perl — quindi qualunque linguaggio tu provenga, uno di questi ti sembrerà familiare.

Commenti a Riga Singola

Un commento a riga singola fa sì che PHP ignori il resto della riga corrente. PHP offre due marcatori intercambiabili per questo: // (stile C) e # (stile shell). Si comportano in modo identico — scegline uno e mantieni la coerenza all'interno di un progetto.

<?php
// This is a single-line comment (C-style)
echo "Hello, world!";

# This is also a single-line comment (shell-style)
echo " Goodbye!";

echo " Done."; // a comment can also follow code on the same line

Il commento termina all'interruzione di riga, quindi le istruzioni echo vengono comunque eseguite. Lo script sopra stampa Hello, world! Goodbye! Done.

Commenti Multi-Riga

Un commento multi-riga inizia con /* e termina con */. Tutto ciò che si trova tra questi marcatori viene ignorato, anche su molte righe. Usalo per spiegazioni più lunghe o per commentare un blocco di codice tutto in una volta.

<?php
/* This is a multi-line comment.
   It can span as many lines as you need,
   which is handy for longer explanations. */
echo "Visible output";

/* You can also keep it on a single line */ echo " — still works";

Le due istruzioni echo stampano Visible output — still works; tutto ciò che si trova all'interno di /* ... */ viene saltato.

Attenzione — i commenti a blocco non si annidano. PHP termina il commento al primo */ che trova. Se racchiudi del codice che contiene già un commento /* ... */, il blocco esterno termina prima del previsto e il */ rimanente causa un errore di analisi. Per disabilitare un pezzo di codice che contiene già commenti a blocco, usa invece // o # su ogni riga.

Perché Usare i Commenti PHP?

I commenti PHP sono uno strumento importante per gli sviluppatori, poiché aiutano a rendere il codice più facile da capire e mantenere. Aggiungendo commenti al codice, puoi spiegare lo scopo di righe di codice specifiche o fornire informazioni aggiuntive sul codice. Questo facilita la comprensione e la manutenzione del codice da parte di altri sviluppatori, e ti aiuta anche a ricordare cosa fa il tuo codice se ci torni in seguito.

Come Usare i Commenti PHP

Per aggiungere un commento al codice PHP, inizia semplicemente la riga con due barre oblique (per i commenti a riga singola) o una barra obliqua e un asterisco (per i commenti multi-riga). È importante scegliere il tipo di commento appropriato in base alle dimensioni e alla complessità del codice che stai commentando.

È anche importante assicurarsi che i commenti siano chiari e concisi, e che forniscano informazioni significative sul codice. Evita di usare i commenti per ripetere semplicemente il codice o per affermare l'ovvio. Concentrati invece sul fornire informazioni che non sono immediatamente evidenti dal codice.

Commentare il Codice Durante il Debug

Uno degli usi più pratici dei commenti è disabilitare temporaneamente il codice senza eliminarlo. Aggiungi come prefisso // o # a una riga, oppure racchiudi più righe in /* ... */, per escluderle dal programma:

<?php
$total = 10 + 5;
// echo $total;        // disabled: don't print yet
echo "Total calculated";

Ricorda la regola del non annidamento sopra: se il codice che vuoi disabilitare contiene già un blocco /* */, commentalo riga per riga con //.

Commenti di Documentazione (PHPDoc)

Oltre ai commenti semplici, l'ecosistema PHP ha una convenzione di documentazione chiamata PHPDoc. È un commento a blocco che inizia con /** (due asterischi) e usa tag @ per descrivere funzioni, parametri e valori di ritorno. IDE e strumenti come phpDocumentor li leggono per fornire il completamento automatico e generare documentazione API.

<?php
/**
 * Adds two numbers together.
 *
 * @param int $a The first number.
 * @param int $b The second number.
 * @return int The sum of the two numbers.
 */
function add($a, $b)
{
    return $a + $b;
}

echo add(2, 3); // 5

PHPDoc è tecnicamente solo un normale commento /* */ per il motore PHP — non ha effetti a runtime — ma seguire la convenzione rende le tue funzioni molto più facili da capire per editor e colleghi. Lo vedrai ampiamente nel capitolo Funzioni PHP.

Best Practice per i Commenti PHP

Ecco alcune best practice da seguire quando si usano i commenti PHP:

• Usa un linguaggio chiaro e conciso nei tuoi commenti
• Evita di ripetere il codice nei commenti — spiega il perché, non il cosa
• Concentrati sul fornire informazioni che non sono immediatamente evidenti dal codice
• Usa livelli di dettaglio appropriati nei tuoi commenti
• Mantieni i commenti aggiornati man mano che il codice si evolve — un commento obsoleto è peggio di nessuno
• Preferisci nomi di variabili e funzioni autoesplicativi ai commenti che spiegano quelli poco chiari

Conclusione

I commenti PHP sono uno strumento essenziale per gli sviluppatori, che consente loro di rendere il codice più facile da capire e mantenere. PHP offre tre sintassi — // e # per le righe singole e /* ... */ per i blocchi — più la convenzione PHPDoc per documentare le funzioni. Seguendo le best practice descritte in questo articolo, puoi sfruttare al massimo i commenti PHP e garantire che il tuo codice sia ben documentato e facile da capire per altri sviluppatori.

Per continuare ad apprendere, passa a Variabili PHP e Operatori PHP.

Esercitazione