Documentación en Go: escribe código que habla por sí mismo

Por qué la documentación en Go es un superpoder, no una obligación aburrida

Imagina: abres un proyecto Go de otra persona y no hay ni un solo comentario. Las funciones se llaman f1, f2, y las estructuras Data y MoreData. ¿Te suena familiar? Si es así, sabes lo rápido que el entusiasmo se convierte en ganas de cerrar el repositorio.

Go es un lenguaje que adora la simplicidad y la claridad. Pero incluso el código más limpio no siempre habla por sí mismo. Una buena documentación en Go no es solo un "gesto amable" para los colegas. Es una herramienta profesional que:

\n
• Acelera la incorporación de nuevos desarrolladores;
\n
• Ayuda a evitar errores (¿recuerdas que los comentarios pueden salvar de un mal uso de la API?);
\n
• Genera automáticamente páginas atractivas en pkg.go.dev;
\n
• Mejora la calidad del código (intenta escribir un comentario para una función mala: querrás reescribirla tú mismo).
\n

En este artículo, analizaremos las mejores prácticas para documentar proyectos Go. Desde las reglas básicas de godoc hasta ejemplos reales que podrás aplicar hoy mismo. ¡Vamos allá!

Filosofía de la documentación en Go: menos palabras, más significado

Go no es Java ni Python. Aquí nadie escribe Javadoc de varias páginas o docstrings de 20 líneas. La filosofía de Go es simple: documenta el comportamiento, no la implementación.

En la guía oficial Effective Go se dice claramente: los comentarios deben describir qué hace el código, no cómo. Si tu código es tan complejo que necesita una explicación del algoritmo, quizás deberías simplificarlo.

Principios básicos:

\n
• El comentario es una oración. Comienza con el nombre de la función o tipo. // Calculate returns the result of the calculation. — excelente. // This function calculates... — pierde el foco.
\n
• Escribe en inglés. Go es un lenguaje internacional, y la documentación en inglés es el estándar de facto. Pero si tu proyecto es estrictamente para un equipo hispanohablante, puedes hacerlo en español. Lo importante es la uniformidad.
\n
• No expliques lo obvio. // SetName sets the name — es inútil. Mejor: // SetName updates the user's display name. Must be called before Save.
\n

Godoc: tu mejor amigo y documentador automático

Go viene con la herramienta integrada godoc. Analiza los comentarios directamente del código y crea documentación HTML. Esto significa que tu documentación vive junto al código y se actualiza al mismo tiempo.

¿Cómo funciona? Muy simple. Escribe un comentario justo antes de la entidad exportada (función, tipo, estructura, constante) y godoc lo recogerá.

Ejemplo de un paquete básico:

// Package calculator provides basic arithmetic operations.\npackage calculator\n\n// Add returns the sum of two integers.\nfunc Add(a, b int) int {\n    return a + b\n}\n\n// Subtract returns the difference of two integers.\nfunc Subtract(a, b int) int {\n    return a - b\n}

Ahora ejecuta godoc -http :8080 y abre el navegador. Verás una página atractiva con la descripción del paquete y de cada función. ¡Magia!

Reglas de buena práctica para godoc

\n
• Comenta siempre el paquete. El comentario del paquete es lo primero que ve el usuario. Debe describir el propósito del paquete e, idealmente, contener un ejemplo de uso.
\n
• No olvides los tipos y estructuras. Si la estructura tiene campos que no son obvios por su nombre, documéntalos también.
\n
• Usa una línea en blanco. godoc interpreta el primer párrafo como una descripción breve y el resto como detalles. Sepáralos con una línea en blanco.
\n

// User repre