Cultura de Revisão de Código para Go
Normas de revisão, diretrizes para 'nitpicks' e ensino através de PRs.
//
Busque em todas as páginas da documentação
Normas de revisão, diretrizes para 'nitpicks' e ensino através de PRs.
Pull requests são a principal sala de aula para idiomatismos Go na maioria das equipes.
Uma cultura de revisão saudável captura bugs precocemente, espalha conhecimento e mantém APIs estáveis sem esgotar autores ou revisores.
A cultura de revisão Go equilibra merge rápido com alta confiança.
Revisores focam no comportamento em falhas, segurança de concorrência, promessas da API exportada e ganchos operacionais.
Preferências cosméticas cedem lugar ao gofmt e linters.
O ensino ocorre em comentários com justificativa e links, não em exigências sem explicação.
Cartão de receita de referência rápida - pronto para copiar e colar.
## Checklist de descrição de PR (autor)
- [ ] Issue ou ticket de incidente vinculado
- [ ] go test ./... e golangci-lint run (colar ou link do CI)
- [ ] -race run se tocar em goroutines, mapas compartilhados entre goroutines ou primitivas de sincronização
- [ ] Anotar alterações de API que quebram e passos de migração
- [ ] Capturas de tela ou linhas de log de exemplo para alterações de comportamento observáveisQuando usar isso:
Revisor examina um PR de handler que retorna erros incorretamente.
// Antes - revisor bloqueia: envolve sem %w, loga e retorna o mesmo err
func (s *Server) fetchUser(ctx context.Context, id string) (*User, error) {
u, err := s.repo.Get(ctx, id)
if err != nil {
log.Printf("get user: %v", err)
return nil, fmt.Errorf("get user: %v", err)
}
return u, nil
}// Depois - política de tratamento única: envolve com %w, mapeia para HTTP na borda do handler
func (s *Server) fetchUser(ctx context.Context, id string) (*User, error) {
u, err := s.repo.Get(ctx, id)
if err != nil {
return nil, fmt.Errorf("fetch user %s: %w", id, err)
}
return u, nil
}
func (s *Server) handleUser(w http.ResponseWriter, r *http.Request) {
u, err := s.fetchUser(r.Context(), r.PathValue("id"))
if err != nil {
if errors.Is(err, ErrNotFound) {
http.NotFound(w, r)
return
}
http.Error(w, "internal error", http.StatusInternalServerError)
return
}
json.NewEncoder(w).Encode(u)
}O que isso demonstra:
%w para errors.Is nas bordas.ErrNotFound.| Prioridade | Procurar | Comentário de exemplo |
|---|---|---|
| P0 | Corridas de dados, panics em caminhos quentes | "Mapa compartilhado sem mutex; execute -race" |
| P1 | Semântica de erro incorreta | "Use %w para que o handler possa errors.Is" |
| P2 | Superfície da API/exportação | "Este tipo é público; godoc e estabilidade?" |
| P3 | Testes ausentes em alteração de comportamento | "Adicionar subteste para o caminho de cancelamento" |
| P4 | Observabilidade | "5xx deve logar o ID da requisição" |
| P5 | Nomenclatura/estilo | "Considere renomear" apenas se confuso |
// Revisores esperam context como primeiro parâmetro após o receiver
func (c *Client) Do(ctx context.Context, req *Request) (*Response, error)
// Sinaliza o armazenamento de context em structs
type Bad struct {
ctx context.Context // revisão: não armazene context
}Ensine aceite interfaces, retorne structs mostrando uma interface mínima definida pelo consumidor em arquivos de teste.
staticcheck via golangci-lint.sync, canais ou errgroup.| Alternativa | Usar Quando | Não Usar Quando |
|---|---|---|
| Pair antes de submeter | Autor é novo em concorrência | Mudança trivial apenas de documentação |
| Mob review | Correções de incidentes de aprendizado | Pequenos PRs diários |
| CODEOWNERS auto-assign | Espalhar conhecimento de domínio | Único guardião de todos os arquivos |
| Gate apenas com lint | Nits repetidos objetivos | Julgamentos sobre design de API |
Bloqueie em correção e ADRs da equipe. Envie nits como sugestões opcionais, a menos que automatizados. Promova nits repetidos para linters.
Para mudanças arriscadas, sim. Para diffs pequenos com CI verde, ler diffs de teste pode ser suficiente. Confie, mas verifique em concorrência.
Mesmo padrão que código humano. O autor deve explicar o design; revisores observam concorrência plausível-mas-errada e atualizações de módulo ruins.
Use quando os problemas são acompanhamentos não bloqueantes rastreados em tickets. Nunca para itens P0-P1.
Incentive perguntas e feedback sobre legibilidade de testes. Seniores modelam respostas graciosas para construir segurança psicológica.
Para novas exportações, sim. Para refatorações internas, corrija o godoc no mesmo PR ou abra um acompanhamento antes da próxima tag de release.
Sincronização curta ou spike de ADR. Padrão para o padrão documentado da equipe até que o ADR mude.
Primeira resposta em um dia útil; revisão completa em dois para PRs médios. Escalar bloqueadores explicitamente.
Sim, para escolhas específicas da equipe: mapeamento de erros, layout de módulos, nomes de campos de observabilidade, padrões de framework.
Espera-se que seniores deixem comentários educativos e melhorem as diretrizes de acordo com o Guia de Nivelamento.
Versões de Stack: Esta página foi escrita para Go 1.26.x (GC padrão Green Tea, go fix modernizers - verificar patch na compilação), chi (latest - verificar na compilação), gin (latest - verificar na compilação), echo (latest - verificar na compilação), google.golang.org/grpc (latest - verificar na compilação), sigs.k8s.io/controller-runtime (latest - verificar na compilação), kubebuilder (latest - verificar na compilação), tinygo (latest - verificar alvos de placa na compilação), wazero (latest - verificar na compilação) e golangci-lint (latest - verificar conjunto de linters na compilação).
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026