Prácticas recomendadas de linting y calidad de código

Equilibrio entre rigurosidad, velocidad y adopción incremental.

Estas reglas destilan la sección de linting-quality: automatizar las comprobaciones aburridas, aumentar la rigurosidad del linter con la base de código y mantener la CI como autoridad.

Cómo usar esta lista

• Aplicar al definir estándares de plataforma o auditar un servicio antes del lanzamiento a producción
• Comenzar los repositorios nuevos en Nivel A; promocionar a Nivel B después del primer lanzamiento
• Emparejar con make check en CONTRIBUTING y comprobaciones de estado de CI requeridas
• Revisar trimestralmente cuando las versiones menores de Go añadan comprobaciones de vet o los valores predeterminados de golangci-lint cambien
• Usar Estándares de revisión de código para equipos de Go para elementos de juicio humano

A - Bases no negociables

• Aplicar gofmt o goimports en CI. El código sin formato nunca se fusiona; proporcionar make fmt para correcciones con un solo comando.
• Ejecutar go vet ./... en cada PR. Vet apunta a errores probables que el compilador omite.
• Requerir go test ./... en verde. La calidad incluye el comportamiento; el lint no puede reemplazar las pruebas.
• Fijar la versión de Go en CI para que coincida con go.mod. La deriva de la cadena de herramientas causa compilaciones falsamente verdes o falsamente rojas.
• Documentar la configuración local en README. Pasos de instalación para goimports, golangci-lint y make check.

B - Puertas de fusión de CI

• Añadir go test -race para servicios con concurrencia. Los fallos de carrera bloquean la fusión, no los correos electrónicos nocturnos.
• Ejecutar golangci-lint con una lista explícita de habilitación. Evitar nuevos linters predeterminados sorpresa fijando la versión de la acción.
• Ejecutar govulncheck en ./... después de cambios en módulos. Clasificar las CVE alcanzables con PR de actualización, no ignorarlas silenciosamente.
• Verificar que go mod tidy no produce ninguna diferencia. Mantiene go.sum honesto en la revisión.
• Excluir *.pb.go generados y mocks de los linters de estilo. Compilar y probar el código generado de todos modos.

C - Experiencia del desarrollador local

• Mantener los hooks de pre-commit por debajo de ~60 segundos. El lint pesado pertenece a pre-push o CI, no a cada commit de WIP.
• Hacer coincidir los prefijos -local de los hooks y las versiones de las herramientas con la CI. Elimina la fricción de "pasa localmente, falla en el pipeline".
• Habilitar el formato gopls al guardar alineado con la política de goimports. Los editores detectan problemas antes de que se ejecuten los hooks.
• Proporcionar objetivos make lint y make test-race. Un vocabulario para humanos y agentes.
• Restringir --no-verify a emergencias con seguimiento. Documentar en el acuerdo del equipo.

D - Rigurosidad incremental

• Habilitar staticcheck después de que vet esté limpio durante un sprint. Los códigos SA encuentran APIs muertas y mal uso.
• Añadir gosec al manejar HTTP, SQL o criptografía. Los linters de seguridad complementan los escaneos de módulos de govulncheck.
• Usar //nolint con ID de ticket y alcance estrecho. Nunca deshabilitar linters en paquetes sin propietarios de forma generalizada.
• Dar de baja las reglas de exclusión con fechas. Las exclusiones de directorios heredados necesitan plazos de refactorización.
• Actualizar golangci-lint según lo programado, no ad hoc. Leer el registro de cambios; corregir los nuevos hallazgos en un PR dedicado.

E - Revisión y cultura

• Tratar el lint como el suelo, la revisión como el techo. Los revisores comprueban el contexto, los errores y la operabilidad según la hoja de trucos.
• No debatir el formato en los comentarios. Señalar make fmt y seguir adelante.
• Celebrar la reducción de las supresiones de linter. Reducir la cuenta de //nolint cada trimestre.
• Compartir nuevos fallos de analizadores vet después de las actualizaciones de Go. Publicar resumen en #eng cuando las notas de lanzamiento añadan comprobaciones.
• Alinear explícitamente las políticas de bibliotecas y servicios. Los módulos publicados pueden ser un poco más estrictos en los linters de API.

Preguntas frecuentes

Relacionado

• Calidad de código Go: Diseñado con opinión - explicación de la sección
• Conceptos básicos de calidad de código - introducción práctica
• Configuración de golangci-lint - profundidad de configuración
• Puertas de calidad de CI: Lint, Test, Race, Vuln - plantilla de pipeline
• staticcheck y golangci-lint en CI - patrones de CI de analizadores

Versiones de pila: Esta página se escribió para Go 1.26.x (predeterminado de Green Tea GC, modernizadores de go fix - verificar parche en la compilación), chi (última - verificar en la compilación), gin (última - verificar en la compilación), echo (última - verificar en la compilación), google.golang.org/grpc (última - verificar en la compilación), sigs.k8s.io/controller-runtime (última - verificar en la compilación), kubebuilder (última - verificar en la compilación), tinygo (última - verificar objetivos de placa en la compilación), wazero (última - verificar en la compilación) y golangci-lint (última - verificar conjunto de linters en la compilación).