Estándares de Codificación y Convenciones de Documentación para Equipos
Los estándares Go del equipo traducen los modismos de la comunidad en reglas de revisión que tu CI puede hacer cumplir.
//
Busca en todas las páginas de la documentación
Los estándares Go del equipo traducen los modismos de la comunidad en reglas de revisión que tu CI puede hacer cumplir.
Esta hoja de trucos recopila las reglas que los ingenieros senior repiten cada sprint para que los nuevos empleados y los linters se alineen más rápido.
//nolint debe citar el ID del ADR).go vet agregue analizadores.| Regla | Aplicación | Justificación |
|---|---|---|
gofmt al guardar/CI | gofmt -l . falla la compilación | Único formateador oficial |
Orden de goimports | goimports -local github.com/yourco | Bloques de importación estables |
| Longitud de línea ~100-120 | golines o revisión | El ajuste de línea es trabajo de gofmt, no de saltos arbitrarios |
| Nombres de archivo | snake_case.go para pruebas _test.go | Coincide con las convenciones de la biblioteca estándar |
| Diseño de paquetes | cmd/, internal/, pkg/ o directorios de dominio | Documenta qué patrón usa tu organización |
| Símbolo | Convención | Ejemplo |
|---|---|---|
| Paquetes | cortos, minúsculas, sin guiones bajos | billing, no billing_service |
| Interfaces | definidas por el consumidor, -er cuando es natural | type Store interface { Save(...) } en el paquete del llamador |
| Errores | variables ErrFoo, tipos FooError | var ErrNotFound = errors.New("billing: not found") |
| Constructores | NewT o NewTWithOpts | func NewServer(cfg Config) *Server |
| Ayudantes de prueba | prefijo helper_ o t.Helper() | Evita exportar símbolos solo para pruebas |
| Genéricos | parámetros de tipo cortos pero significativos | func Map[T, U any](...) |
| Regla | Patrón de código | Disparador de revisión |
|---|---|---|
Envolver con %w | fmt.Errorf("load cfg: %w", err) | Retornos desnudos que cruzan límites de paquetes |
| Errores centinela documentados | godoc en var Err... | Cambiar el texto centinela es una ruptura |
context primer parámetro | func Fetch(ctx context.Context, id string) | Falta ctx en IO o RPC |
No usar panic en bibliotecas | devolver errores | panic solo en main o mala configuración de init |
%v vs %w | registrar con %v, envolver con %w | Registrar la cadena envuelta incorrectamente |
if err := db.Save(ctx, rec); err != nil {
return fmt.Errorf("billing: save invoice %s: %w", rec.ID, err)
}| Regla | Herramientas | Notas |
|---|---|---|
| Pruebas basadas en tablas | subpruebas t.Run | Nombra los casos para mayor claridad en fallos |
-race en CI | go test -race ./... | Requerido para paquetes de concurrencia |
| Ejemplos compilan | go test ejecuta Example_* | La documentación se mantiene honesta en CI |
| Objetivos de cobertura | definidos por el equipo por nivel de paquete | Bibliotecas más altas que main |
No usar sleep en pruebas | usar canales, synctest cuando esté disponible | Las pruebas inestables son defectos |
| Elemento | Regla | Ejemplo |
|---|---|---|
| Comentario de paquete | Uno por paquete, bloque package foo | Explicar el propósito, no la implementación |
| Función exportada | Comienza con el nombre de la función | // Parse lee ... para Parse |
| Obsoleto | // Deprecated: use NewParse | Enlazar problema de migración |
| Parámetros | Nombre en el comentario cuando no es obvio | // ctx transporta el plazo para RPC salientes. |
| Sección de errores | Documentar errores devueltos | // Devuelve ErrNotFound cuando ... |
| Funciones de ejemplo | En _test.go, // Output: | Aparece en pkg.go.dev |
// Package billing implementa el almacenamiento de facturas para el servicio de pagos.
package billing
// Parse lee un ID de factura de la entrada bruta del usuario.
// Devuelve ErrInvalidID cuando el formato no es ULID.
func Parse(id string) (InvoiceID, error)| Linter | Detecta | Habilitar cuando |
|---|---|---|
govet | analizadores de la biblioteca estándar | Siempre |
staticcheck | deprecaciones de API, errores | Siempre |
errcheck | errores ignorados | Siempre |
ineffassign | asignaciones muertas | Siempre |
gosec | olores de seguridad | Ajustar falsos positivos por ADR |
revive | estilo más allá de gofmt | Alinear reglas con la guía escrita |
gocritic | simplificaciones de opinión | Después del taller del equipo |
# Extracto de .golangci.yml - alinear con esta hoja de trucos
linters:
enable:
- govet
- staticcheck
- errcheck
- ineffassign
run:
timeout: 5m| Situación | Respuesta estándar | Documentar |
|---|---|---|
| Nueva dependencia externa | Revisión de licencia + ruta del módulo | DEP-ADR |
unsafe o cgo | Segundo revisor requerido | SEC-ADR |
| Ruptura de API exportada | Módulo de versión mayor o solo interno | API-ADR |
//nolint | El comentario cita la regla + ADR | STYLE-ADR |
go vet ignorado | Prohibido sin aprobación de la plataforma | TOOL-ADR |
gofmt solo maneja el diseño.
Los equipos aún necesitan reglas para errores, contexto, interfaces y política de dependencias.
Úsalo como base.
Adapta secciones donde las restricciones de tu monorepo difieran y registra las diferencias en los ADR.
Mantén los parámetros de tipo cortos en ayudantes pequeños; las API exportadas merecen nombres de restricciones descriptivos.
Documenta las convenciones de etiquetas JSON/protobuf una vez.
Haz cumplir a través de linters (tagalign) si la deriva es común.
Las funciones Example deben estar en las pruebas para compilar como documentación.
Usa comentarios regulares para la narrativa en otros lugares.
Prefiere el ajuste de gofmt.
Los límites duros importan principalmente para exclusiones de código generado.
Las mismas reglas de godoc, pero exportado significa "exportado a otros equipos", aún comenta las API internas estables.
Ejecuta los nuevos linters en modo warn durante un sprint, luego promuévelos a fail.
Sí, a través de make lint que refleja la CI.
Los autores no deben depender de los revisores como linters.
Effective Go es la fuente filosófica.
Esta hoja de trucos es una política de equipo aplicable derivada de ella más tus ADR.
Versiones de Stack: Esta página fue escrita para Go 1.26.x (predeterminado de Green Tea GC, go fix modernizadores - verifica el parche en la compilación), chi (última versión - verifica en la compilación), gin (última versión - verifica en la compilación), echo (última versión - verifica en la compilación), google.golang.org/grpc (última versión - verifica en la compilación), sigs.k8s.io/controller-runtime (última versión - verifica en la compilación), kubebuilder (última versión - verifica en la compilación), tinygo (última versión - verifica los objetivos de la placa en la compilación), wazero (última versión - verifica en la compilación) y golangci-lint (última versión - verifica el conjunto de linters en la compilación).
Revisado por Chris St. John·Última actualización: 19 jul 2026