Boas Práticas de Linting e Qualidade de Código

Q: Qual é a barra mínima de qualidade viável?

gofmt, go vet e go test ./... em CI. Adicione golangci-lint e race quando a equipe tiver mais do que um punhado de pacotes.

Q: Como monorepos evitam trabalhos de lint de 30 minutos?

Particione por módulo em matriz, cache de módulos, use --new-from-rev em PRs. Mantenha a varredura completa do repositório noturna.

Q: Como os gates de qualidade interagem com os modernizadores do go fix?

Execute go fix em branches de upgrade; comite separadamente do trabalho de feature. Vet pode falhar até que os modernizadores sejam aplicados.

Equilibrando rigor, velocidade e adoção incremental.

Estas regras destilam a seção de linting-quality: automatize as verificações tediosas, aumente o rigor dos linters com a base de código e mantenha a CI como autoridade.

Como Usar Esta Lista

Aplique ao definir padrões de plataforma ou auditar um serviço antes do lançamento em produção
Comece novos repos em Tier A; promova para Tier B após o primeiro lançamento
Emparelhe com make check em CONTRIBUTING e verifique os status de CI obrigatórios
Revise trimestralmente quando as atualizações menores do Go adicionarem verificações de vet ou as configurações padrão do golangci-lint mudarem
Use Padrões de Revisão de Código para Equipes Go para itens de julgamento humano

A - Bases não negociáveis

Aplique gofmt ou goimports em CI. Código não formatado nunca é mesclado; forneça make fmt para correções com um comando.
Execute go vet ./... em todo PR. Vet visa bugs prováveis que o compilador perde.
Exija go test ./... verde. A qualidade inclui comportamento; lint não pode substituir testes.
Fixe a versão do Go em CI para corresponder a go.mod. Desvios na toolchain causam builds falsos verdes ou falsos vermelhos.
Documente a configuração local no README. Passos de instalação para goimports, golangci-lint e make check.

B - Portões de mesclagem de CI

Adicione go test -race para serviços com concorrência. Falhas de race bloqueiam a mesclagem, não e-mails noturnos.
Execute golangci-lint com lista explícita de habilitação. Evite novos linters padrão surpresa fixando a versão da ação.
Execute govulncheck em ./... após alterações de módulo. Triagem de CVEs alcançáveis com PRs de upgrade, não ignorando silenciosamente.
Verifique se go mod tidy não produz diferenças. Mantém go.sum honesto na revisão.
Exclua *.pb.go gerados e mocks de linters de estilo. Ainda compile e teste o código gerado.

C - Experiência do desenvolvedor local

Mantenha os hooks de pre-commit abaixo de ~60 segundos. Lint pesado pertence ao pre-push ou CI, não a cada commit WIP.
Combine prefixos de hook -local e versões de ferramenta com a CI. Elimina o atrito "passa localmente, falha no pipeline".
Ative a formatação gopls ao salvar alinhada com a política do goimports. Editores capturam problemas antes que os hooks sejam executados.
Forneça alvos make lint e make test-race. Um vocabulário para humanos e agentes.
Restrinja --no-verify a emergências com acompanhamento. Documente no acordo da equipe.

D - Rigor incremental

Ative staticcheck após vet estar limpo por um sprint. Códigos SA encontram APIs mortas e mau uso.
Adicione gosec ao lidar com HTTP, SQL ou criptografia. Linters de segurança complementam as varreduras de módulo do govulncheck.
Use //nolint com ID de ticket e escopo restrito. Nunca desabilite linters em pacotes sem proprietários de forma genérica.
Desative regras de exclusão com datas. Exclusões de diretório legadas precisam de prazos de refatoração.
Atualize golangci-lint em agendamento, não ad hoc. Leia o changelog; corrija novas descobertas em um PR dedicado.

E - Revisão e cultura

Trate lint como o piso, revisão como o teto. Revisores verificam contexto, erros e operabilidade por cheatsheet.
Não debata formatação em comentários. Aponte para make fmt e siga em frente.
Celebre a redução de supressões de linter. Tendência da contagem de //nolint para baixo a cada trimestre.
Compartilhe novas falhas de analisador vet após atualizações do Go. Poste um resumo em #eng quando as notas de release adicionarem verificações.
Alinhe explicitamente as políticas de biblioteca e serviço. Módulos publicados podem permanecer um pouco mais rigorosos em linters de API.

FAQs

Qual é a barra mínima de qualidade viável?

gofmt, go vet e go test ./... em CI.

Adicione golangci-lint e race quando a equipe tiver mais do que um punhado de pacotes.

Quão rigoroso o golangci-lint deve ser no primeiro dia?

Comece com govet, errcheck, gosimple, ineffassign, unused, staticcheck.

Adicione revive e gosec após a linha de base de ruído ser zero.

Projetos OSS devem usar os mesmos gates que serviços internos?

OSS pode permanecer em format + vet + test para reduzir o atrito do contribuinte.

Execute govulncheck e race na CI do mantenedor antes das tags.

Como monorepos evitam trabalhos de lint de 30 minutos?

Particione por módulo em matriz, cache de módulos, use --new-from-rev em PRs.

Mantenha a varredura completa do repositório noturna.

Quando lint customizado vale a pena?

Quando staticcheck não consegue expressar regras de API estáveis da organização.

Mantenha analisadores customizados como código de produção.

E sobre builds tinygo ou wasm?

Escopo do lint para pacotes que compilam para cada destino.

Documente as tags de build excluídas em .golangci.yml.

Como os gates de qualidade interagem com os modernizadores do go fix?

Execute go fix em branches de upgrade; comite separadamente do trabalho de feature.

Vet pode falhar até que os modernizadores sejam aplicados.

A qualidade deve bloquear hotfixes?

Hotfixes ainda precisam de testes e vet.

Documente a revisão acelerada, não pule race/vuln em caminhos de produção.

Relacionados

Qualidade de Código Go: Opinativo por Design - explicador da seção
Noções Básicas de Qualidade de Código - introdução prática
Configuração do golangci-lint - profundidade de configuração
Gates de Qualidade de CI: Lint, Test, Race, Vuln - template de pipeline
staticcheck & golangci-lint em CI - padrões de CI de analisador

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, modernizadores go fix - verifique o patch na build), chi (latest - verifique na build), gin (latest - verifique na build), echo (latest - verifique na build), google.golang.org/grpc (latest - verifique na build), sigs.k8s.io/controller-runtime (latest - verifique na build), kubebuilder (latest - verifique na build), tinygo (latest - verifique os alvos de placa na build), wazero (latest - verifique na build) e golangci-lint (latest - verifique o conjunto de linters na build).

Boas Práticas de Linting e Qualidade de Código

Equilibrando rigor, velocidade e adoção incremental.

Estas regras destilam a seção de linting-quality: automatize as verificações tediosas, aumente o rigor dos linters com a base de código e mantenha a CI como autoridade.

Como Usar Esta Lista

Aplique ao definir padrões de plataforma ou auditar um serviço antes do lançamento em produção
Comece novos repos em Tier A; promova para Tier B após o primeiro lançamento
Emparelhe com make check em CONTRIBUTING e verifique os status de CI obrigatórios
Revise trimestralmente quando as atualizações menores do Go adicionarem verificações de vet ou as configurações padrão do golangci-lint mudarem
Use Padrões de Revisão de Código para Equipes Go para itens de julgamento humano

A - Bases não negociáveis

Aplique gofmt ou goimports em CI. Código não formatado nunca é mesclado; forneça make fmt para correções com um comando.
Execute go vet ./... em todo PR. Vet visa bugs prováveis que o compilador perde.
Exija go test ./... verde. A qualidade inclui comportamento; lint não pode substituir testes.
Fixe a versão do Go em CI para corresponder a go.mod. Desvios na toolchain causam builds falsos verdes ou falsos vermelhos.
Documente a configuração local no README. Passos de instalação para goimports, golangci-lint e make check.

B - Portões de mesclagem de CI

Adicione go test -race para serviços com concorrência. Falhas de race bloqueiam a mesclagem, não e-mails noturnos.
Execute golangci-lint com lista explícita de habilitação. Evite novos linters padrão surpresa fixando a versão da ação.
Execute govulncheck em ./... após alterações de módulo. Triagem de CVEs alcançáveis com PRs de upgrade, não ignorando silenciosamente.
Verifique se go mod tidy não produz diferenças. Mantém go.sum honesto na revisão.
Exclua *.pb.go gerados e mocks de linters de estilo. Ainda compile e teste o código gerado.

C - Experiência do desenvolvedor local

Mantenha os hooks de pre-commit abaixo de ~60 segundos. Lint pesado pertence ao pre-push ou CI, não a cada commit WIP.
Combine prefixos de hook -local e versões de ferramenta com a CI. Elimina o atrito "passa localmente, falha no pipeline".
Ative a formatação gopls ao salvar alinhada com a política do goimports. Editores capturam problemas antes que os hooks sejam executados.
Forneça alvos make lint e make test-race. Um vocabulário para humanos e agentes.
Restrinja --no-verify a emergências com acompanhamento. Documente no acordo da equipe.

D - Rigor incremental

Ative staticcheck após vet estar limpo por um sprint. Códigos SA encontram APIs mortas e mau uso.
Adicione gosec ao lidar com HTTP, SQL ou criptografia. Linters de segurança complementam as varreduras de módulo do govulncheck.
Use //nolint com ID de ticket e escopo restrito. Nunca desabilite linters em pacotes sem proprietários de forma genérica.
Desative regras de exclusão com datas. Exclusões de diretório legadas precisam de prazos de refatoração.
Atualize golangci-lint em agendamento, não ad hoc. Leia o changelog; corrija novas descobertas em um PR dedicado.

E - Revisão e cultura

Trate lint como o piso, revisão como o teto. Revisores verificam contexto, erros e operabilidade por cheatsheet.
Não debata formatação em comentários. Aponte para make fmt e siga em frente.
Celebre a redução de supressões de linter. Tendência da contagem de //nolint para baixo a cada trimestre.
Compartilhe novas falhas de analisador vet após atualizações do Go. Poste um resumo em #eng quando as notas de release adicionarem verificações.
Alinhe explicitamente as políticas de biblioteca e serviço. Módulos publicados podem permanecer um pouco mais rigorosos em linters de API.

FAQs

Qual é a barra mínima de qualidade viável?

gofmt, go vet e go test ./... em CI.

Adicione golangci-lint e race quando a equipe tiver mais do que um punhado de pacotes.

Quão rigoroso o golangci-lint deve ser no primeiro dia?

Comece com govet, errcheck, gosimple, ineffassign, unused, staticcheck.

Adicione revive e gosec após a linha de base de ruído ser zero.

Projetos OSS devem usar os mesmos gates que serviços internos?

OSS pode permanecer em format + vet + test para reduzir o atrito do contribuinte.

Execute govulncheck e race na CI do mantenedor antes das tags.

Como monorepos evitam trabalhos de lint de 30 minutos?

Particione por módulo em matriz, cache de módulos, use --new-from-rev em PRs.

Mantenha a varredura completa do repositório noturna.

Quando lint customizado vale a pena?

Quando staticcheck não consegue expressar regras de API estáveis da organização.

Mantenha analisadores customizados como código de produção.

E sobre builds tinygo ou wasm?

Escopo do lint para pacotes que compilam para cada destino.

Documente as tags de build excluídas em .golangci.yml.

Como os gates de qualidade interagem com os modernizadores do go fix?

Execute go fix em branches de upgrade; comite separadamente do trabalho de feature.

Vet pode falhar até que os modernizadores sejam aplicados.

A qualidade deve bloquear hotfixes?

Hotfixes ainda precisam de testes e vet.

Documente a revisão acelerada, não pule race/vuln em caminhos de produção.

Relacionados

Qualidade de Código Go: Opinativo por Design - explicador da seção
Noções Básicas de Qualidade de Código - introdução prática
Configuração do golangci-lint - profundidade de configuração
Gates de Qualidade de CI: Lint, Test, Race, Vuln - template de pipeline
staticcheck & golangci-lint em CI - padrões de CI de analisador

Versões de Stack: Esta página foi escrita para Go 1.26.x (padrão Green Tea GC, modernizadores go fix - verifique o patch na build), chi (latest - verifique na build), gin (latest - verifique na build), echo (latest - verifique na build), google.golang.org/grpc (latest - verifique na build), sigs.k8s.io/controller-runtime (latest - verifique na build), kubebuilder (latest - verifique na build), tinygo (latest - verifique os alvos de placa na build), wazero (latest - verifique na build) e golangci-lint (latest - verifique o conjunto de linters na build).

Boas Práticas de Linting e Qualidade de Código

Buscar na documentação

Boas Práticas de Linting e Qualidade de Código