Padrões de Codificação e Convenções de Documentação para Equipes

Q: Exemplos podem viver fora de _test.go?

Funções Example devem estar em testes para compilar como documentação. Use comentários regulares para narrativa em outros lugares.

Q: Como integramos linters sem congelar a CI?

Execute novos linters no modo warn por um sprint, depois promova para fail.

Q: Os revisores devem executar o golangci-lint localmente?

Sim, via make lint, espelhando a CI. Os autores não devem depender dos revisores como linters.

Padrões Go de equipe traduzem idiomas da comunidade em regras de revisão que sua CI pode aplicar.

Esta cheatsheet coleta as regras que engenheiros seniores repetem a cada sprint para que novos contratados e linters se alinhem mais rapidamente.

Como Usar Esta Cheatsheet

Copie seções para seu guia de estilo interno; vincule cada regra a um nome de linter, se possível.
Habilite regras gradualmente no golangci-lint em vez de ativar predefinições inteiras de uma vez.
Emparelhe com um índice de ADRs para exceções intencionais (//nolint deve citar o ID do ADR).
Revise após os lançamentos menores de Go, quando go vet adicionar analisadores.

Formatação e Layout

Regra	Aplicação	Justificativa
`gofmt` ao salvar/CI	`gofmt -l .` falha a compilação	Único formatador oficial
Ordenação do `goimports`	`goimports -local github.com/yourco`	Blocos de importação estáveis
Comprimento da linha ~100-120	`golines` ou revisão	Quebras de linha são trabalho do gofmt, não quebras arbitrárias
Nomes de arquivo	`snake_case.go` para testes `_test.go`	Corresponde às convenções da biblioteca padrão
Layout do pacote	`cmd/`, `internal/`, `pkg/` ou diretórios de domínio	Documente qual padrão sua organização usa

Nomenclatura e Superfície da API

Símbolo	Convenção	Exemplo
Pacotes	curtos, minúsculos, sem sublinhados	`billing`, não `billing_service`
Interfaces	definidas pelo consumidor, `-er` quando natural	`type Store interface { Save(...) }` no pacote chamador
Erros	variáveis `ErrFoo`, tipos `FooError`	`var ErrNotFound = errors.New("billing: not found")`
Construtores	`NewT` ou `NewTWithOpts`	`func NewServer(cfg Config) *Server`
Auxiliares de teste	prefixo `helper_` ou `t.Helper()`	Evite exportar símbolos apenas para teste
Genéricos	parâmetros de tipo curtos, mas significativos	`func Map[T, U any](...)`

Erros e Contexto

Regra	Padrão de código	Gatilho de revisão
Envolver com `%w`	`fmt.Errorf("load cfg: %w", err)`	Retornos nus cruzando limites de pacotes
Erros sentinela documentados	godoc em `var Err...`	Alterar texto sentinela é quebra
`context` como primeiro parâmetro	`func Fetch(ctx context.Context, id string)`	Falta de ctx em IO ou RPC
Sem `panic` em bibliotecas	retornar erros	`panic` apenas em `main` ou erro de configuração
`%v` vs `%w`	registrar com `%v`, envolver com `%w`	Registrar cadeia envolvida incorretamente

if err := db.Save(ctx, rec); err != nil {
    return fmt.Errorf("billing: save invoice %s: %w", rec.ID, err)
}

Padrões de Teste

Regra	Ferramentas	Notas
Testes orientados por tabela	subtestes `t.Run`	Nomeie casos para clareza de falha
`-race` em CI	`go test -race ./...`	Necessário para pacotes de concorrência
Exemplos compilam	`go test` executa `Example_*`	Documentos permanecem honestos em CI
Metas de cobertura	definidas pela equipe por nível de pacote	Bibliotecas têm prioridade maior que `main`
Sem `sleep` em testes	use canais, `synctest` quando disponível	Testes instáveis são defeitos

Convenções do godoc

Elemento	Regra	Exemplo
Comentário do pacote	Um por pacote, bloco `package foo`	Explique o propósito, não a implementação
Função exportada	Começa com o nome da função	`// Parse lê ...` para `Parse`
Obsoleto	`// Deprecated: use NewParse`	Vincule o problema de migração
Parâmetros	Nome no comentário quando não óbvio	`// ctx carrega o prazo para RPC de saída.`
Seção de erros	Documente os erros retornados	`// Retorna ErrNotFound quando ...`
Funções de exemplo	Em `_test.go`, `// Output:`	Aparece em pkg.go.dev

// Package billing implementa o armazenamento de faturas para o serviço de pagamentos.
package billing
 
// Parse lê um ID de fatura da entrada bruta do usuário.
// Retorna ErrInvalidID quando o formato não é ULID.
func Parse(id string) (InvoiceID, error)

Conjunto Inicial do golangci-lint

Linter	Detecta	Habilitar quando
`govet`	analisadores da biblioteca padrão	Sempre
`staticcheck`	depreciações de API, bugs	Sempre
`errcheck`	erros ignorados	Sempre
`ineffassign`	atribuições mortas	Sempre
`gosec`	cheiros de segurança	Ajuste falsos positivos por ADR
`revive`	estilo além do gofmt	Alinhe regras com o guia escrito
`gocritic`	simplificações opinativas	Após workshop da equipe

# Trecho do .golangci.yml - alinhe com esta cheatsheet
linters:
  enable:
    - govet
    - staticcheck
    - errcheck
    - ineffassign
run:
  timeout: 5m

Ganchos de Revisão e ADR

Situação	Resposta padrão	Documento
Nova dependência externa	Revisão de licença + caminho do módulo	DEP-ADR
`unsafe` ou `cgo`	Segundo revisor necessário	SEC-ADR
Quebra de API exportada	Módulo de versão principal ou apenas interno	API-ADR
`//nolint`	Comentário cita regra + ADR	STYLE-ADR
`go vet` ignorado	Proibido sem aprovação da plataforma	TOOL-ADR

FAQs

O gofmt é suficiente sem um guia de estilo escrito?

gofmt lida apenas com o layout.

As equipes ainda precisam de regras para erros, contexto, interfaces e política de dependência.

Devemos aplicar o Guia de Estilo Go do Google literalmente?

Use-o como base.

Adapte seções onde as restrições do seu monorepo diferem e registre as diferenças em ADRs.

Como os genéricos mudam as regras de nomenclatura?

Mantenha os parâmetros de tipo curtos em auxiliares pequenos; APIs exportadas merecem nomes de restrição descritivos.

Onde as tags de struct pertencem nas regras de estilo?

Documente as convenções de tags JSON/protobuf uma vez.

Aplique via linters (tagalign) se a deriva for comum.

Exemplos podem viver fora de `_test.go`?

Funções Example devem estar em testes para compilar como documentação.

Use comentários regulares para narrativa em outros lugares.

Quão rigoroso deve ser o comprimento da linha?

Prefira o wrapping do gofmt.

Limites rígidos importam principalmente para exclusões de código gerado.

E quanto aos pacotes internos?

Mesmas regras do godoc, mas exportado significa "exportado para outras equipes" - ainda comente APIs internas estáveis.

Como integramos linters sem congelar a CI?

Execute novos linters no modo warn por um sprint, depois promova para fail.

Os revisores devem executar o golangci-lint localmente?

Sim, via make lint, espelhando a CI.

Os autores não devem depender dos revisores como linters.

Como isso se relaciona com o Go Eficaz?

O Go Eficaz é a fonte filosófica.

Esta cheatsheet é uma política de equipe aplicável derivada dele, mais seus ADRs.

Relacionados

Noções Básicas de Comunidade e Governança - índice de padrões da primeira semana
Governança de Dependências e Conformidade de Licença - política de módulos
Comunidade Go e Artesanato de Longo Prazo - sustentando padrões ao longo do tempo
Padrões, Governança e Melhores Práticas da Comunidade - checklist de hábitos da equipe
Convenções de Documentação e godoc - padrões mais profundos do godoc

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

Esta cheatsheet coleta as regras que engenheiros seniores repetem a cada sprint para que novos contratados e linters se alinhem mais rapidamente.

Como Usar Esta Cheatsheet

Copie seções para seu guia de estilo interno; vincule cada regra a um nome de linter, se possível.
Habilite regras gradualmente no golangci-lint em vez de ativar predefinições inteiras de uma vez.
Emparelhe com um índice de ADRs para exceções intencionais (//nolint deve citar o ID do ADR).
Revise após os lançamentos menores de Go, quando go vet adicionar analisadores.

Formatação e Layout

Regra	Aplicação	Justificativa
`gofmt` ao salvar/CI	`gofmt -l .` falha a compilação	Único formatador oficial
Ordenação do `goimports`	`goimports -local github.com/yourco`	Blocos de importação estáveis
Comprimento da linha ~100-120	`golines` ou revisão	Quebras de linha são trabalho do gofmt, não quebras arbitrárias
Nomes de arquivo	`snake_case.go` para testes `_test.go`	Corresponde às convenções da biblioteca padrão
Layout do pacote	`cmd/`, `internal/`, `pkg/` ou diretórios de domínio	Documente qual padrão sua organização usa

Nomenclatura e Superfície da API

Símbolo	Convenção	Exemplo
Pacotes	curtos, minúsculos, sem sublinhados	`billing`, não `billing_service`
Interfaces	definidas pelo consumidor, `-er` quando natural	`type Store interface { Save(...) }` no pacote chamador
Erros	variáveis `ErrFoo`, tipos `FooError`	`var ErrNotFound = errors.New("billing: not found")`
Construtores	`NewT` ou `NewTWithOpts`	`func NewServer(cfg Config) *Server`
Auxiliares de teste	prefixo `helper_` ou `t.Helper()`	Evite exportar símbolos apenas para teste
Genéricos	parâmetros de tipo curtos, mas significativos	`func Map[T, U any](...)`

Erros e Contexto

Regra	Padrão de código	Gatilho de revisão
Envolver com `%w`	`fmt.Errorf("load cfg: %w", err)`	Retornos nus cruzando limites de pacotes
Erros sentinela documentados	godoc em `var Err...`	Alterar texto sentinela é quebra
`context` como primeiro parâmetro	`func Fetch(ctx context.Context, id string)`	Falta de ctx em IO ou RPC
Sem `panic` em bibliotecas	retornar erros	`panic` apenas em `main` ou erro de configuração
`%v` vs `%w`	registrar com `%v`, envolver com `%w`	Registrar cadeia envolvida incorretamente

if err := db.Save(ctx, rec); err != nil {
    return fmt.Errorf("billing: save invoice %s: %w", rec.ID, err)
}

Padrões de Teste

Regra	Ferramentas	Notas
Testes orientados por tabela	subtestes `t.Run`	Nomeie casos para clareza de falha
`-race` em CI	`go test -race ./...`	Necessário para pacotes de concorrência
Exemplos compilam	`go test` executa `Example_*`	Documentos permanecem honestos em CI
Metas de cobertura	definidas pela equipe por nível de pacote	Bibliotecas têm prioridade maior que `main`
Sem `sleep` em testes	use canais, `synctest` quando disponível	Testes instáveis são defeitos

Convenções do godoc

Elemento	Regra	Exemplo
Comentário do pacote	Um por pacote, bloco `package foo`	Explique o propósito, não a implementação
Função exportada	Começa com o nome da função	`// Parse lê ...` para `Parse`
Obsoleto	`// Deprecated: use NewParse`	Vincule o problema de migração
Parâmetros	Nome no comentário quando não óbvio	`// ctx carrega o prazo para RPC de saída.`
Seção de erros	Documente os erros retornados	`// Retorna ErrNotFound quando ...`
Funções de exemplo	Em `_test.go`, `// Output:`	Aparece em pkg.go.dev

// Package billing implementa o armazenamento de faturas para o serviço de pagamentos.
package billing
 
// Parse lê um ID de fatura da entrada bruta do usuário.
// Retorna ErrInvalidID quando o formato não é ULID.
func Parse(id string) (InvoiceID, error)

Conjunto Inicial do golangci-lint

Linter	Detecta	Habilitar quando
`govet`	analisadores da biblioteca padrão	Sempre
`staticcheck`	depreciações de API, bugs	Sempre
`errcheck`	erros ignorados	Sempre
`ineffassign`	atribuições mortas	Sempre
`gosec`	cheiros de segurança	Ajuste falsos positivos por ADR
`revive`	estilo além do gofmt	Alinhe regras com o guia escrito
`gocritic`	simplificações opinativas	Após workshop da equipe

# Trecho do .golangci.yml - alinhe com esta cheatsheet
linters:
  enable:
    - govet
    - staticcheck
    - errcheck
    - ineffassign
run:
  timeout: 5m

Ganchos de Revisão e ADR

Situação	Resposta padrão	Documento
Nova dependência externa	Revisão de licença + caminho do módulo	DEP-ADR
`unsafe` ou `cgo`	Segundo revisor necessário	SEC-ADR
Quebra de API exportada	Módulo de versão principal ou apenas interno	API-ADR
`//nolint`	Comentário cita regra + ADR	STYLE-ADR
`go vet` ignorado	Proibido sem aprovação da plataforma	TOOL-ADR

FAQs

O gofmt é suficiente sem um guia de estilo escrito?

gofmt lida apenas com o layout.

As equipes ainda precisam de regras para erros, contexto, interfaces e política de dependência.

Devemos aplicar o Guia de Estilo Go do Google literalmente?

Use-o como base.

Adapte seções onde as restrições do seu monorepo diferem e registre as diferenças em ADRs.

Como os genéricos mudam as regras de nomenclatura?

Mantenha os parâmetros de tipo curtos em auxiliares pequenos; APIs exportadas merecem nomes de restrição descritivos.

Onde as tags de struct pertencem nas regras de estilo?

Documente as convenções de tags JSON/protobuf uma vez.

Aplique via linters (tagalign) se a deriva for comum.

Exemplos podem viver fora de `_test.go`?

Funções Example devem estar em testes para compilar como documentação.

Use comentários regulares para narrativa em outros lugares.

Quão rigoroso deve ser o comprimento da linha?

Prefira o wrapping do gofmt.

Limites rígidos importam principalmente para exclusões de código gerado.

E quanto aos pacotes internos?

Mesmas regras do godoc, mas exportado significa "exportado para outras equipes" - ainda comente APIs internas estáveis.

Como integramos linters sem congelar a CI?

Execute novos linters no modo warn por um sprint, depois promova para fail.

Os revisores devem executar o golangci-lint localmente?

Sim, via make lint, espelhando a CI.

Os autores não devem depender dos revisores como linters.

Como isso se relaciona com o Go Eficaz?

O Go Eficaz é a fonte filosófica.

Esta cheatsheet é uma política de equipe aplicável derivada dele, mais seus ADRs.

Relacionados

Noções Básicas de Comunidade e Governança - índice de padrões da primeira semana
Governança de Dependências e Conformidade de Licença - política de módulos
Comunidade Go e Artesanato de Longo Prazo - sustentando padrões ao longo do tempo
Padrões, Governança e Melhores Práticas da Comunidade - checklist de hábitos da equipe
Convenções de Documentação e godoc - padrões mais profundos do godoc

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

Padrões de Codificação e Convenções de Documentação para Equipes

Buscar na documentação

Padrões de Codificação e Convenções de Documentação para Equipes