Commento (informatica)

Codice Java con un commento introduttivo

Il commento, nell'ambito dei linguaggi di programmazione, è una sequenza delimitata di caratteri nel codice sorgente che non risulta nell'algoritmo risolutivo codificato e che solitamente ha lo scopo di descriverne le caratteristiche funzionali, ovvero di spiegare il funzionamento delle linee di codice adiacenti.

Durante il processo di compilazione o interpretazione queste istruzioni sono ignorate e di conseguenza non concorrono a determinare la difficoltà computazionale e il peso del file eseguibile^[1]. Queste notazioni hanno particolare rilevanza, soprattutto se il programma è sviluppato da più collaboratori e in un ampio arco temporale, infatti aumenta la leggibilità (o intelligibilità) per il lettore e favorisce così manutenzione e aggiornamento del codice. I commenti vengono spesso usati anche per omettere temporaneamente l'esecuzione di alcune porzioni di codice, in modo che non vengano eseguite senza tuttavia rimuoverle dal codice sorgente stesso. Quest'ultima pratica è spesso usata in fase di debugging del programma.

Panoramica

I commenti sono generalmente formattati come commenti di blocco (chiamati anche commenti di prologo o commenti di flusso) o commenti di riga (chiamati anche commenti in linea)^[2].

I commenti di blocco delimitano un'area del codice sorgente che può estendersi su più righe o su una parte di una singola riga. Questa regione è specificata con un delimitatore iniziale e un delimitatore finale. Alcuni linguaggi di programmazione (come MATLAB) consentono di annidare ricorsivamente i commenti a blocchi, al contrario di altri (come Java)^[3]^[4]^[5].

I commenti di riga iniziano con un delimitatore e continuano fino alla fine della riga o, in alcuni casi, iniziano da una colonna specifica (offset di riga dei caratteri) nel codice sorgente e continuano fino alla fine della riga^[5].

Alcuni linguaggi di programmazione utilizzano commenti di blocco e di riga con delimitatori di commento diversi. Ad esempio, C++ ha commenti di blocco delimitati da /* e */ che possono estendersi su più righe, mentre i commenti di riga sono delimitati da //. Altre tipologie di linguaggio supportano solo un tipo di commento, ad esempio i commenti in Ada possono essere solo di linea: iniziano con -- e continuano fino alla fine della riga^[5].

Sollievo dallo stress

A volte i programmatori aggiungono commenti per alleviare lo stress criticando gli strumenti di sviluppo, i concorrenti, i datori di lavoro, le condizioni di lavoro o la qualità del codice stesso. Il verificarsi di questo fenomeno può essere facilmente visto dalle risorse online che tracciano parolacce nel codice sorgente^[6].

Descrizione

Linguaggi di programmazione

Ogni linguaggio possiede una propria sintassi per permettere al programmatore di inserire commenti nel codice. Nella tabella sottostante sono riportate le indicazioni relative ad alcuni dei più utilizzati linguaggi di programmazione e di markup^[7].

Linguaggio	Commento di riga	Commento di blocco
Assembly	`;`
Autoit	`;`	`#cs #ce`
BASIC	`REM` oppure `'`
Bash	`#`
C	`//`	`/* */`
C++	`//`	`/* */`
C#	`//`	`/* */`
Cobol	`*` nella settima colonna
Fortran	`!`
HTML		<!-- -->
Java	`//`	`/* */`
JavaScript	`//`	`/* */`
Matlab	`%`	`%{ ... %}`
Pascal		`{ }` oppure `(* *)`
PHP	`//` oppure `#`	`/* */`
Python	`#`	`""" """`
YAML	`#`	`#`

Problemi di sicurezza

Nei linguaggi interpretati i commenti sono visualizzabili dall'utente finale nel codice del programma. In alcuni casi, ciò potrebbe presentare una vulnerabilità di sicurezza^[8].

Normative

Esistono vari punti di vista normativi e opinioni di lunga data sull'uso corretto dei commenti nel codice sorgente^[9]^[10]. Alcuni di questi sono informali e basati sulle preferenze personali, mentre altri sono pubblicati o promulgati come linee guida formali per una particolare comunità o gruppo di lavoro^[11].

Necessità di commenti

Gli esperti di informatica teorica hanno punti di vista divergenti sull'opportuna quantità e posizione di commenti nel codice sorgente^[12]^[13]. Alcuni affermano che dovrebbe contenere pochi commenti, basandosi sul fatto che il codice dovrebbe essere auto esplicativo (o auto-documentante)^[12]. Altri suggeriscono che dovrebbe essere ampiamente commentato per aumentarne chiarezza e leggibilità (non è raro che oltre il 50% dei caratteri diversi da spazi nel file sorgente siano contenuti nei commenti)^{[senza fonte]}.

I sostenitori di ambedue i punti di vista concordano che i commenti non sono di per sé né vantaggiosi né dannosi, ma ciò che conta è che siano corretti e mantenuti inerenti al codice sorgente, o omessi se superflui, eccessivi, inefficaci o comunque inutili.

I commenti vengono talvolta utilizzati per documentare i contratti nei progetti su commissione.

Esempio

// esegue un ciclo all'indietro attraverso tutti gli elementi restituiti dal server (devono essere elaborati cronologicamente) 
for(i = (numElementsReturned - 1 ); i >= 0 ;  i--){ 
    // elabora i dati di ogni elemento
    updatePattern(i, returnElements[i]); 
}

Note

^ (EN) H. James de St. Germain, Commenting, su University of Utah, 2008. URL consultato il 31 agosto 2023.
^ J.B. Dixit, Computer Fundamentals and Programming in C, Laxmi Publications, 2003, ISBN 978-81-7008-882-0.
^ Desmond Higham, MATLAB Guide, SIAM, 2005, ISBN 978-0-89871-578-1.
^ Al Vermeulen, The Elements of Java Style, Cambridge University Press, 2000, ISBN 978-0-521-77768-1.
^ ^a ^b ^c Using the right comment in Java, su javadude.com, 4 marzo 2000. URL consultato il 24 luglio 2007.
^ Linux kernel word count, su vidarholen.net. URL consultato il 15 marzo 2021.
^ Jessica Keyes, Software Engineering Handbook, CRC Press, 2003, ISBN 978-0-8493-1479-7. discusses comments and the "Science of Documentation" p. 256.
^ Mandy Andress, Surviving Security: How to Integrate People, Process, and Technology, CRC Press, 2003, ISBN 978-0-8493-2042-2.
^ Pete Goodliffe, Code Craft, San Francisco, No Starch Press, 2006, ISBN 978-1-59327-119-0.
^ T. Smith, Intermediate Programming Principles and Techniques Using Pascal, Belmont, West Pub. Co, 1991, ISBN 978-0-314-66314-6.
^ See e.g., Peter Koletzke, Oracle Developer Advanced Forms & Reports, Berkeley, Osborne/McGraw-Hill, 2000, ISBN 978-0-07-212048-6. page 65.
^ ^a ^b The Elements of Programming Style, Kernighan & Plauger
^ Worst Practice - Bad Comments, su sqlservercentral.com. URL consultato il 24 luglio 2007.