Convenciones de Documentación y godoc
Comentarios de paquete, ejemplos y playbooks internos.
//
Busca en todas las páginas de la documentación
Comentarios de paquete, ejemplos y playbooks internos.
La documentación de Go son comentarios interpretados por go doc y pkg.go.dev.
Los equipos que tratan la documentación como parte de la API reducen la fricción en la incorporación, mejoran la calidad de la revisión y hacen que el material de referencia generado sea confiable.
godoc es la superficie de referencia predeterminada para los paquetes de Go.
Los comentarios de paquete explican el propósito y los patrones de uso.
Los comentarios de símbolos documentan el comportamiento, las reglas de concurrencia y la semántica de errores.
Los ejemplos proporcionan fragmentos ejecutables.
Los playbooks internos cubren runbooks y pasos de incorporación que godoc no debería intentar contener.
Tarjeta de receta de referencia rápida, lista para copiar y pegar.
// Package ratelimit proporciona limitación de velocidad de bucket de tokens para manejadores HTTP.
//
// Usa NewLimiter al inicio del proceso y comparte un único Limiter entre manejadores.
// Los limitadores son seguros para uso concurrente.
package ratelimit
// Limiter controla la tasa de solicitudes usando un bucket de tokens.
type Limiter struct { /* ... */ }
// Allow informa si un evento puede proceder en el momento now.
// Es seguro para uso concurrente por múltiples goroutines.
func (l *Limiter) Allow(now time.Time) bool { /* ... */ }Cuándo usar esto:
Una biblioteca agrega documentación ejecutable y una descripción general del paquete.
// example_test.go
package ratelimit_test
import (
"fmt"
"time"
"example.com/lib/ratelimit"
)
func ExampleNewLimiter() {
lim := ratelimit.NewLimiter(10, time.Second)
ok := lim.Allow(time.Now())
fmt.Println(ok)
// Output: true
}go test -run Example
go doc example.com/lib/ratelimitLo que esto demuestra:
*_test.go con el prefijo Example y // Output: opcional.go test ejecuta los ejemplos como pruebas; los ejemplos rotos fallan CI.Limiter.package (solo un archivo por paquete debe contener el bloque principal).| Elemento | Regla |
|---|---|
| func/type/const Exportado | El comentario comienza con el nombre; indica lo que hace |
| Errores | Documenta las condiciones de retorno y la reintentabilidad |
| Contexto | Nota los efectos de cancelación |
| Concurrencia | Indica explícitamente si es seguro o no |
| Valor cero | Indica si el valor cero es útil |
| Obsoleto | // Deprecated: usa NewX en su lugar |
// Malo - el comentario no comienza con el nombre del símbolo
// Devuelve un limitador para control de velocidad.
func NewLimiter(rate int, window time.Duration) *Limiter
// Bueno
// NewLimiter devuelve un Limiter que permite 'rate' eventos por 'window'.
func NewLimiter(rate int, window time.Duration) *Limiter// ErrRateExceeded indica que el cliente excedió la cuota.
// Los llamadores pueden reintentar después de la duración RetryAfter.
var ErrRateExceeded = errors.New("tasa excedida")Enlaza tipos relacionados con nombres de texto plano; godoc enlaza automáticamente identificadores cuando es posible.
doc.go o un archivo designado por paquete.httptest.Server con salida determinista.| Alternativa | Usar Cuando | No Usar Cuando |
|---|---|---|
| Solo README | Herramientas de línea de comandos internas | Bibliotecas exportadas consumidas por otros equipos |
| OpenAPI para HTTP | La superficie REST es el contrato principal | Bibliotecas puras de Go sin HTTP |
| Comentarios de Protobuf | gRPC es la API principal | Los ayudantes de cliente de Go escritos a mano aún necesitan godoc |
| Documentación generada (swaggo) | Superficie HTTP grande | Todavía necesitas comentarios de Go a nivel de paquete para la lógica |
Documenta los elementos no exportados cuando la complejidad lo exija, pero godoc no los mostrará en pkg.go.dev. Prefiere nombres claros para los elementos internos.
De una a tres oraciones para la mayoría de los símbolos. El texto más extenso pertenece al comentario del paquete o a los documentos de diseño en markdown enlazados desde README.
Los nombres de las pruebas y los casos de tabla son documentación para los compañeros de equipo. Usa funciones Example cuando quieras fragmentos para pkg.go.dev.
Agrega una línea Deprecated: con el reemplazo y la línea de tiempo. Los revisores bloquean nuevos usos de símbolos obsoletos en el código de la aplicación.
Sí, cuando las API necesiten genéricos o nuevos símbolos de la biblioteca estándar. Alinea con la directiva go del módulo en go.mod.
Coincide con la política del equipo. Los idiomas mixtos perjudican la búsqueda y la incorporación; la mayoría de las bases de código de producción se estandarizan en inglés para las exportaciones.
Ejecuta go test para ejemplos, opcionalmente go vet y linters que verifican las oraciones de los comentarios en las exportaciones.
Los propietarios de servicios rotan la revisión trimestral de los enlaces de README y runbook; los equipos de plataforma poseen las plantillas compartidas.
Los ADRs registran el porqué; godoc registra el qué y el cómo. Enlaza los ADRs en README, no en cada comentario de función.
Los autores deben verificar la precisión con respecto a las rutas de código y los errores. Los revisores tratan el godoc incorrecto como un error bloqueante.
go docVersiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de GC Green Tea, go fix modernizers - verificar parche en la compilación), chi (última versión - verificar en la compilación), gin (última versión - verificar en la compilación), echo (última versión - verificar en la compilación), google.golang.org/grpc (última versión - verificar en la compilación), sigs.k8s.io/controller-runtime (última versión - verificar en la compilación), kubebuilder (última versión - verificar en la compilación), tinygo (última versión - verificar objetivos de placa en la compilación), wazero (última versión - verificar en la compilación) y golangci-lint (última versión - verificar conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 16 jul 2026