En Go, la documentación no es un archivo externo que se escribe “después” de programar; es una parte integral del código mediante los doc comments. Estos son comentarios especiales que siguen una convención de formato muy estricta para que herramientas como go doc o el sitio pkg.go.dev puedan transformarlos automáticamente en una página web legible.
Para que esto funcione, el compilador y las herramientas de documentación necesitan identificar exactamente a qué símbolo (una función, un tipo, una variable o un paquete) pertenece el comentario. Por eso, el diseño de Go exige que el comentario comience con el nombre del elemento que está documentando. Si no sigues esta regla, la herramienta simplemente ignorará el texto y el símbolo aparecerá sin descripción. Esta decisión de diseño busca la localidad de la referencia: al mantener la documentación justo encima del código, se garantiza que, cuando cambies el nombre de una función, el comentario te “salte a la vista” para ser actualizado, evitando que la documentación se convierta en una mentira con el paso del tiempo.
Debes usar este estilo siempre que definas algo exportado (cualquier cosa que empiece con mayúscula). Si lo haces mal, tu código será difícil de usar para otros y la documentación automática aparecerá vacía, lo que en entornos profesionales es un error crítico de mantenimiento.
package main
import (
"fmt"
"math"
)
// Calculadora representa un motor de operaciones matemáticas simples.
type Calculadora struct {
Factor float64
}
// Operar realiza una suma entre dos valores y aplica el factor de la calculadora.
// El resultado final se procesa con [math.Abs] para asegurar un valor positivo.
func (c *Calculadora) Operar(a, b float64) float64 {
res := (a + b) * c.Factor
return math.Abs(res)
}
func main() {
calc := Calculadora{Factor: 2.5}
// Mostramos el resultado de la operación
resultado := calc.Operar(10, 5)
fmt.Printf("Resultado: %.2f\n", resultado)
}
En el código anterior, la documentación comienza con el tipo Calculadora. Si fíjate en la línea // Calculadora representa..., el comentario empieza exactamente con el nombre del struct. Lo mismo ocurre con el método Operar, cuyo comentario inicia con la palabra Operar.
Un detalle clave de modernidad es el uso de [math.Abs]. Introducido en Go 1.19, este formato permite crear referencias cruzadas automáticas. Cuando la herramienta de documentación procesa este comentario, detecta que math.Abs es otro símbolo y crea un enlace directo hacia la documentación oficial de la librería math. Esto es fundamental para navegar entre paquetes sin tener que buscar manualmente en otros sitios. Finalmente, el cuerpo del comentario en Operar utiliza un párrafo estándar para explicar la lógica de negocio, lo cual se renderiza como un bloque de texto limpio en la documentación final.
El error frecuente
Un error muy común es intentar documentar una función de forma natural, olvidando la convención de inicio:
// Suma dos números de forma rápida. // ERROR: No empieza con "Suma"
func (c *Calculadora) Suma(a, b float64) float64 {
return a + b
}
Aunque parezca un detalle trivial, para go doc este comentario es solo un comentario normal y no una documentación. Para que el sistema lo reconozca, debe ser: // Suma suma dos números....
N° 14