Comentarios en

Acerca de Comentarios

Los comentarios te permiten dejar notas en el código sin afectar a cómo se ejecuta. Un comentario de una sola línea empieza por // en cualquier punto de una línea. El compilador ignora todo lo que hay desde // hasta el final de esa línea. Cuando un comentario aparece después del código en la misma línea, se suele llamar comentario en línea. Un comentario de varias líneas empieza por /* y termina en */ en cualquier punto de una línea. El compilador ignora todo lo que hay entre medias, abarque una o varias líneas.

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

Los comentarios cumplen distintas funciones según dónde aparezcan.

Comentarios de código

Los comentarios de código explican por qué se hace algo, no qué se hace. Úsalos cuando el motivo que hay detrás de una decisión no se vea claro en el código:

results = results[1:] // skipping the header row

En la mayoría de los casos, el código bien escrito se explica por sí solo y no necesita comentarios. En ocasiones, es necesario que el código haga algo complejo o inesperado; ese tipo de código sí conviene comentarlo.

Comentarios de documentación

Los comentarios de documentación se usan para documentar un paquete, una variable o una función. Esta documentación va dirigida a otras personas que programan y quieren saber cómo usar tu código. Debe explicar, a grandes rasgos, qué hace el código y cómo usarlo. No debe incluir detalles sobre cómo funciona el código por dentro. Los comentarios de documentación se colocan justo antes de una declaración, sin ninguna línea en blanco que separe el comentario de la declaración. godoc los analiza para generar la documentación del paquete, como se ve en pkg.go.dev. Un comentario de documentación debe ser una oración completa que empiece por el nombre del identificador y termine con un punto.

Los comentarios de documentación de los identificadores exportados (los que empiezan por mayúscula) aparecen en la documentación generada. Los comentarios de documentación de los identificadores no exportados (los que no empiezan por mayúscula) no aparecerán, pero aun así pueden aportar contexto útil dentro del código.

Los comentarios que documentan paquetes empiezan por el nombre del paquete y describen qué hace el paquete:

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

Los comentarios que documentan funciones empiezan por el nombre de la función y describen qué hace la función, incluidos sus argumentos y sus valores devueltos:

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

Los comentarios que documentan variables empiezan por el nombre de la variable y describen qué representa la variable:

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

Para consultar la especificación completa de los comentarios de documentación, echa un vistazo a la guía de documentación de Go.