Comentarios en

Acerca de Comentarios

Los comentarios te permiten dejar notas en el código sin afectar cómo se ejecuta. Un comentario de una sola línea comienza con // en cualquier parte de una línea. El compilador ignora todo, desde // hasta el final de esa línea. Cuando un comentario va después del código en la misma línea, a menudo se le llama comentario en línea. Un comentario multilínea comienza con /* y termina con */ en cualquier parte de una línea. El compilador ignora todo lo que hay en medio, aunque abarque una o más 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 la razón detrás de una decisión no sea evidente 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. De vez en cuando, 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 está 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 de cómo funciona el código en sí. Los comentarios de documentación van justo antes de una declaración, sin ninguna línea en blanco entre el comentario y 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 con el nombre del identificador y termine con un punto.

Los comentarios de documentación sobre identificadores exportados (los que empiezan con una letra mayúscula) aparecen en la documentación generada. Los comentarios de documentación sobre identificadores no exportados (los que no empiezan con una letra mayúscula) no aparecerán, pero aún pueden aportar contexto útil dentro del código.

Los comentarios que documentan paquetes comienzan con 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 comienzan con el nombre de la función y describen qué hace la función, incluidos sus argumentos y los valores que devuelve:

// 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 comienzan con 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, mira la guía de documentación de Go.