Commenti in Go

I commenti in Go servono per documentare il codice e renderlo più comprensibile. Go ha una cultura forte riguardo alla documentazione tramite commenti, grazie allo strumento godoc.

Commenti su Singola Riga

Si utilizzano le doppie barre //:

// Questa è una variabile che contiene il nome utente
var nome string = "Mario"

x := 10 // Commento alla fine della riga

Commenti su Più Righe

Si utilizzano /* */:

/*
Questo è un commento
che si estende su
più righe.
*/
func calcolaArea(base, altezza float64) float64 {
    return base * altezza / 2
}

Commenti di Documentazione (Godoc)

In Go, i commenti che precedono dichiarazioni esportate diventano automaticamente documentazione. Questo è il sistema godoc:

// Calcolatrice fornisce operazioni matematiche di base.
// Supporta addizione, sottrazione, moltiplicazione e divisione.
type Calcolatrice struct {
    Risultato float64
}

// Somma aggiunge due numeri e restituisce il risultato.
func Somma(a, b float64) float64 {
    return a + b
}

Convenzioni per Godoc

• Il commento deve iniziare con il nome dell’elemento documentato
• Usa frasi complete che terminano con un punto
• La prima frase appare come riassunto

// Package matematica fornisce funzioni per calcoli matematici avanzati.
package matematica

// Pi rappresenta il valore approssimato di pi greco.
const Pi = 3.14159265358979

// MassimoComunDivisore calcola il MCD di due numeri interi
// utilizzando l'algoritmo di Euclide.
func MassimoComunDivisore(a, b int) int {
    for b != 0 {
        a, b = b, a%b
    }
    return a
}

Commenti per Package

Ogni package dovrebbe avere un commento che descrive il suo scopo, posizionato prima della dichiarazione package:

// Package stringutils fornisce funzioni di utilità
// per la manipolazione avanzata delle stringhe.
package stringutils

Per package complessi, si può creare un file doc.go dedicato alla documentazione.

Generare Documentazione

# Visualizza la documentazione nel terminale
go doc nomepacchetto

# Avvia un server web con la documentazione
go doc -http=:6060

Best Practice

• Commenta il perché, non il cosa (il codice dovrebbe essere autoesplicativo)
• Documenta sempre le funzioni e i tipi esportati
• Mantieni i commenti aggiornati con il codice
• Non commentare codice inutilizzato, eliminalo

Conclusione

I commenti in Go non sono solo annotazioni per gli sviluppatori: grazie a godoc diventano documentazione ufficiale del pacchetto. Seguire le convenzioni di Go per i commenti rende il codice più professionale e facilmente comprensibile da altri sviluppatori.