Categoria: Go

Uma das perguntas mais frequentes sobre Go é se existe algum guia de estilo para a escrita de código, como a nomenclatura de variáveis, funções e pacotes, semelhante ao PEP 8 do Python.

Essa dúvida, inclusive, está presente na página de Frequently Asked Questions (FAQ) da documentação oficial da linguagem, na seguinte pergunta:

Is there a Go programming style guide?

E a resposta é:

There is no explicit style guide, although there is certainly a recognizable “Go style”. (Não existe um guia de estilo explícito, embora haja certamente um “estilo Go” reconhecível.)

O que existe são convenções para orientar sobre nomenclatura, layout e organização de arquivos.

O gofmt, ferramenta oficial da linguagem de programação Go, formata automaticamente o código-fonte de acordo com o estilo padrão da linguagem. Embora não seja obrigatório, esse estilo é amplamente adotado pela comunidade como o jeito certo de escrever código Go. O gofmt pode ser integrado a IDEs como o Visual Studio Code, permitindo que a formatação seja aplicada automaticamente sempre que o arquivo for salvo.

Existem também documentos que contêm conselhos sobre esses tópicos, como:

• Effective Go – https://go.dev/doc/effective_go
• Go Code Review Comments – https://go.dev/wiki/CodeReviewComments

O guia mais completo que encontrei até hoje é o Go Style Decisions, publicado pelo Google (vale lembrar que a linguagem Go surgiu dentro da própria empresa). Esse guia é, inclusive, referenciado na documentação oficial do Go, na página Go Code Review Comments.

Considero esse documento minha principal referência quando o assunto é estilo, e abaixo destaco os pontos mais relevantes sobre nomenclatura, segundo a minha visão pessoal:

Nomes

Nomear é mais uma arte do que uma ciência. Em Go, os nomes tendem a ser um pouco mais curtos do que em muitas outras linguagens. Eles não devem ser repetitivos, devem levar o contexto em consideração e não deve repetir conceitos que já são claros.

Underscores _

No código Go, utiliza-se CamelCase em vez de underscores, como no snake_case, para nomes compostos por várias palavras dos identificadores.

Nota: Os nomes dos arquivos de código-fonte não são identificadores Go e, portanto, não precisam seguir as mesmas convenções de nomenclatura. Eles podem conter underscores, como, por exemplo, my_api_handlers.go (isso é até o recomendado para esses casos).

Pacotes

Os nomes dos pacotes devem ser curtos e conter somente letras minúsculas.

Se forem compostos por múltiplas palavras, elas devem ser escritas juntas, sem separação ou caracteres especiais.

Se for necessário importar um pacote cujo nome contenha underscore (geralmente código de terceiros), ele deve ser renomeado durante a importação para um nome mais adequado seguindo as boas práticas.

Seja consistente usando sempre o mesmo nome para o mesmo pacote importado em diferentes arquivos.

Evite usar nomes que também possam ser utilizados por variáveis, a fim de prevenir sombreamento no código.

Exceção a regra:

Quando for necessário testar um pacote como um usuário externo, ou seja, testando apenas sua interface pública, é preciso adicionar o sufixo *_test ao nome do pacote nos arquivos de teste.

Isso força a importação explícita do pacote, permitindo a realização do chamado teste de caixa-preta (black box testing).

Para saber mais, acesse: https://pkg.go.dev/testing.

Receptores (receivers)

Eles devem ser curtos, sendo uma ou duas letras do próprio nome, e usados de forma igual para todos os métodos daquele tipo.

Prefira	Evite
func (t Tray)	func (tray Tray)
func (ri *ResearchInfo)	func (info *ResearchInfo)
func (w *ReportWriter)	func (this *ReportWriter)
func (s *Scanner)	func (self *Scanner)

Constantes

Deve ser utilizado CamelCase, assim como os outros nomes.

Constantes exportadas começam com letra maiúscula, enquanto constantes não exportadas começam com letra minúscula.

Isso se aplica mesmo que contrarie convenções de outras linguagens, como em Java, onde as constantes são geralmente todas maiúsculas e com underscore. Por exemplo, MAX_RETRIES se tornaria MaxRetries em Go.

Além disso, não é necessário começar o nome com a letra “k”.

Siglas

Palavras em nomes que são siglas ou acrônimos (ex: URL e OTAN) devem manter a capitalização (todo maiúsculo ou tudo minúsculo).

Em nomes com múltiplas siglas (ex: XMLAPI, pois contém XML e API), cada letra de uma mesma sigla deve ter a mesma capitalização, mas as siglas diferentes podem usar capitalizações distintas.

Se a sigla contiver letras minúsculas (ex: DDoS, iOS, gRPC), ela deve manter a forma original, a menos que precise mudar a primeira letra para exportação (como em linguagens de programação).

Nome	Escopo	Prefira	Evite
XML API	Exportada	XMLAPI	XmlApi, XMLApi, XmlAPI, XMLapi
XML API	Não exportada	xmlAPI	xmlapi, xmlApi
iOS	Exportada	IOS	Ios, IoS
iOS	Não exportada	iOS	ios
gRPC	Exportada	GRPC	Grpc
gRPC	Não exportada	gRPC	grpc
DDoS	Exportada	DDoS	DDOS, Ddos
DDoS	Não exportada	ddos	dDos, dDOS
ID	Exportada	ID	ID
ID	Não exportada	id	iD
DB	Exportada	DB	Db
DB	Não exportada	db	dB

Getters

Nomes de funções e métodos não devem utilizar o prefixo “Get” ou “get”, a menos que o conceito envolva a palavra “get” de forma natural (como em uma requisição HTTP GET).

Prefira começar o nome diretamente com o substantivo. Por exemplo, use Counts em vez de GetCounts.

Se a função envolve um cálculo complexo ou a execução de uma chamada remota, é recomendável usar palavras como Compute (calcular) ou Fetch (buscar), em vez de Get, para deixar claro ao desenvolvedor que a execução da função pode demorar, bloquear ou falhar.

Repetição

Um código deve evitar repetições desnecessárias, que podem ocorrer de diferentes formas, especialmente na nomeação de pacotes, variáveis, constantes ou funções exportadas.

Nas funções, não repita o nome do pacote:

Mais exemplos:

Prefira	Evite
widget.New	widget.NewWidget
widget.NewWithName	widget.NewWidgetWithName
db.Load	db.LoadFromDatabase
gtutil.CountGoatsTeleported goatteleport.Count	goatteleportutil.CountGoatsTeleported
mtpb.MyTeamMethodRequest myteampb.MethodRequest	myteampb.MyTeamMethodRequest

Nos métodos, não repita o nome do receptor:

Não repita o nome das variáveis passadas por parâmetros:

Não repita os nomes e tipos dos valores de retorno:

Quando for necessário remover a ambiguidade de funções de nomes similares, é aceitável incluir informações adicionais.

Nome da variáveis VS tipo

O compilador sempre conhece o tipo de uma variável, e na maioria dos casos, o tipo também é claro para o desenvolvedor com base em como a variável é utilizada.

Só é necessário especificar o tipo de uma variável quando seu valor aparecer duas vezes no mesmo escopo.

Se o valor aparece em múltiplas formas, isso pode ser esclarecido com o uso de uma palavra adicional, como raw (bruto) e parsed (processado).

Contexto externo VS nomes locais

Nomes que incluem informações já presentes no contexto ao redor geralmente adicionam ruído desnecessário, sem agregar benefícios.

O nome do pacote, do método, do tipo, da função, do caminho de importação e até mesmo o nome do arquivo já fornecem contexto suficiente para qualificar automaticamente todos os nomes dentro deles.

Leitura complementar

Qual seria um tamanho bom de um nome de variável, constantes e função?

A regra é que o tamanho do nome deve ser proporcional ao escopo dele e inversamente proporcional ao número de vezes que ele é usado dentro desse escopo.

Uma variável com escopo de arquivo pode precisar de várias palavras, enquanto uma variável dentro de um bloco interno (como um IF ou um FOR) pode ser um nome curto ou até uma única letra, para manter o código claro e evitar informações desnecessárias.

Aqui está uma orientação (não é regra) do que seria o tamanho de cada escopo em linhas.

• Escopo pequeno: uma ou duas pequenas operações, entre 1 e 7 linhas.
• Escopo médio: algumas pequenas operações ou uma grande operação, entre 8 e 15 linhas.
• Escopo grande: uma ou algumas operações grandes, entre 15 e 25 linhas.
• Escopo muito grande: várias operações que podem envolver diferentes responsabilidades, mais de 25 linhas.

Um nome que é claro em um escopo pequeno (por exemplo, c para um contador) pode não ser suficiente em um escopo maior, exigindo mais clareza para lembrar ao desenvolvedor de seu propósito.

A especificidade do conceito também pode ajudar a manter o nome de uma variável conciso. Por exemplo, se houver apenas um banco de dados em uso, um nome curto como db, que normalmente seria reservado para escopos pequenos, pode continuar claro mesmo em um escopo maior.

Nomes de uma única palavra, como count e options, são um bom ponto de partida. Caso haja ambiguidade, palavras adicionais podem ser incluídas para torná-los mais claros, como userCount e projectCount.

E como dica final: evite remover letras para reduzir o tamanho do nome, como em Sbx em vez de Sandbox, pois isso pode prejudicar a clareza. No entanto, há exceções, como nomes amplamente aceitos pela comunidade de forma reduzida, como db para database e ctx para context.

A ordenação de elementos em um array é uma tarefa frequentemente utilizada em diversos programas. Embora existam muitos algoritmos de ordenação bem conhecidos, ninguém quer ficar copiando blocos de código de um projeto para outro.

Por isso, o Go oferece a biblioteca nativa sort.

Ela permite ordenar arrays in-place (a ordenação é feita diretamente na estrutura de dados original, sem criar uma cópia adicional do array) com qualquer critério de ordenação, utilizando uma abordagem baseada em interfaces.

A função sort.Sort não faz suposições sobre a estrutura dos dados; ela apenas exige que o tipo a ser ordenado implemente a interface sort.Interface, que define três métodos essenciais apresentados a seguir.

Um ótimo exemplo inicial é o tipo sort.StringSlice, fornecido pela própria biblioteca sort. Ele já implementa a interface sort.Interface, conforme mostrado abaixo:

Seguindo essas regras, é possível ordenar structs com base em seus campos como no exemplo a seguir, que ordena uma lista de alunos pela nota:

Com a estrutura já definida, também é possível verificar se o array está ordenado usando sort.IsSorted, além de realizar a ordenação em ordem reversa com sort.Reverse. As funções são demonstradas abaixo, utilizando a mesma estrutura do exemplo anterior.

A biblioteca também oferece outras funções bastante úteis:

• Ints(x []int): ordena uma slice de inteiros em ordem crescente.
• IntsAreSorted(x []int) bool: verifica se o slice x está ordenada em ordem crescente.
• Strings(x []string): ordena um slice de strings em ordem crescente.
• StringsAreSorted(x []string) bool: verifica se a slice x está ordenada em ordem crescente.

ATENÇÃO

Na própria documentação do pacote sort, na data de escrita deste artigo, existe uma nota na função sort.Sort que diz o seguinte:

Em muitas situações, a função mais recente slices.SortFunc é mais ergonômica e apresenta melhor desempenho.

Essa mesma nota se encontra na função sort.IsSorted:

Em muitas situações, a função mais recente slices.IsSortedFunc é mais ergonômica e apresenta melhor desempenho.

Em ambos os casos, recomendo avaliar qual abordagem adotar com base no que for mais vantajoso para a sua situação: a simplicidade das funções do pacote sort ou a possível otimização oferecida pelo pacote slices.

Para descobrir qual delas apresenta melhor desempenho no seu contexto, utilize os benchmarks do Go (fica aqui o dever de casa para você, caro leitor, dar uma conferida nisso).

A partir do Go 1.22, algumas funções do pacote sort já utilizam a biblioteca slices internamente, como é o caso de sort.Ints, que usa slices.Sort, e sort.IntsAreSorted, que usa slices.IsSorted.

Para saber mais, confira as documentações oficiais:

sort: https://pkg.go.dev/sort

slices: https://pkg.go.dev/slices

Referências:

DONOVAN, Alan A. A.; KERNIGHAN, Brian W.. The Go Programming Language. Crawfordsville: Addison-Wesley, 2016.

Documentação oficial da biblioteca sort: https://pkg.go.dev/sort

Documentação oficial da biblioteca slices: https://pkg.go.dev/slices

As funções init são funções especiais que são executadas antes de qualquer função no código.

Elas são a terceira etapa na ordem de inicialização de um programa em Go, sendo:

1. Os pacotes importados são inicializados;
2. As variáveis e constantes globais do pacote são inicializadas;
3. As funções init são executadas.

Seu uso mais comum é preparar o estado do programa antes da execução principal na main, como por exemplo: verificar se variáveis de configuração estão corretamente definidas, checar a existência de arquivos necessários ou até mesmo criar recursos ausentes.

É possível declarar várias funções init em um mesmo pacote e em pacotes diferentes, desde que todas utilizem exatamente o nome init.

Quando isso ocorre, a ordem de execução delas é a seguinte dependendo do caso:

Em pacotes com dependência entre si

Se o pacote A depende do pacote B, a função init do pacote B será executada antes da função init do pacote A.

O Go garante que todos os pacotes importados sejam completamente inicializados antes que o pacote atual comece sua própria inicialização.

Essa dependência entre pacotes também pode ser forçada usando o identificador em branco, ou blank identifier (_), como no exemplo abaixo que o pacote foo será importado e inicializado, mesmo que não seja utilizado diretamente.

Múltiplas funções init no mesmo arquivo

Quando existem várias funções init no mesmo arquivo, elas são executadas na ordem em que aparecem no código.

Múltiplas funções init em arquivos diferentes do mesmo pacote

Nesse caso, a execução segue a ordem alfabética dos arquivos. Por exemplo, se um pacote contém dois arquivos, a.go e b.go e ambos possuem funções init, a função em a.go será executada antes da função em b.go.

No entanto, não devemos depender da ordem de execução das funções init dentro de um mesmo pacote. Isso pode ser arriscado, pois renomeações de arquivos podem alterar a ordem da execução, impactando o comportamento do programa.

Apesar de úteis, as funções init possuem algumas desvantagens e pontos de atenção que devem ser levados em conta na hora de escolher usá-las ou não:

1. Elas podem dificultar o controle e tratamento de erros, pois já que não retornam nenhum valor, nem de erro, uma das únicas formas de tratar problemas em sua execução é via panic, que causa a interrupção da aplicação.
2. Podem complicar a implementação de testes, por exemplo, se uma dependência externa for configurada dentro de init, ela será executada mesmo que não seja necessária para o escopo dos testes unitários. Além de serem executadas antes dos casos de teste, o que pode gerar efeitos colaterais inesperados.
3. A alteração do valor de variáveis globais dentro da função init pode ser uma má prática em alguns contextos:
   • Dificulta testes: como o estado global já foi definido automaticamente pela init, é difícil simular diferentes cenários ou redefinir esse estado nos testes.
   • Aumenta o acoplamento: outras partes do código passam a depender implicitamente do valor dessas variáveis globais, tornando o sistema menos modular.
   • Reduz previsibilidade: como a inicialização acontece automaticamente e sem controle do desenvolvedor, fica mais difícil entender ou modificar o fluxo de execução do programa.
   • Afeta reutilização: bibliotecas que dependem de init com variáveis globais são menos reutilizáveis, pois forçam comportamentos no momento da importação.
     

Em resumo, as funções init são úteis para configurações iniciais, mas seu uso deve ser criterioso, pois podem dificultar testes, tratamento de erros e tornar o código menos previsível.

Referência: HARSANYI, Teiva. 100 Go mistakes and how to avoid them. Shelter Island: Manning, 2022.

Um modelo mental, no contexto de software, é a representação interna que um desenvolvedor constrói para compreender como um sistema ou trecho de código funciona. Ele não é visível, mas sim uma estrutura de raciocínio que permite prever o comportamento do sistema com base no conhecimento adquirido até aquele momento.

Durante a leitura ou escrita de código, o desenvolvedor precisa manter esse modelo atualizado para entender, por exemplo, quais funções interagem entre si, como os dados fluem e quais efeitos colaterais podem ocorrer.

Códigos com boa legibilidade exigem menos esforço cognitivo para manter esses modelos mentais coerentes e atualizados.

Um dos fatores que contribuem para uma boa legibilidade é o alinhamento do código.

Na Golang UK Conference de 2016, Mat Ryer apresentou o conceito de line of sight in code (“linha de visão no código”, em tradução literal). Ele define linha de visão como “uma linha reta ao longo da qual um observador tem visão desobstruída”.

Aplicado ao código, isso significa que uma boa linha de visão não altera o comportamento da função, mas torna mais fácil para outras pessoas entenderem o que está acontecendo.

A ideia é que o leitor consiga acompanhar o fluxo principal de execução olhando para uma única coluna, sem precisar pular entre blocos, interpretar condições ou navegar por estruturas aninhadas.

Uma boa prática é alinhar o caminho feliz da função à esquerda do código. Isso facilita a visualização imediata do fluxo esperado.

O caminho feliz é o fluxo principal de execução de uma função ou sistema, em que tudo ocorre como esperado sem erros, exceções ou desvios.

Na imagem a seguir é possível visualizar um exemplo de caminho feliz:

De modo geral, quanto mais níveis de aninhamento uma função possui, mais difícil ela se torna de ler e entender, além de ocultar o caminho feliz, como podemos ver na imagem abaixo:

Mat Ryer em seu artigo Code: Align the happy path to the left edge apresenta mais dicas para uma boa linha de visão, sendo elas:

Retorne o mais cedo possível de uma função. Essa prática melhora a legibilidade porque reduz o aninhamento e mantém o caminho feliz limpo e direto.

Evite usar else para retornar valores, especialmente quando o if já retorna algo. Em vez disso, inverta a condição if (flip the if) e retorne mais cedo, deixando o fluxo principal fora do else.

Coloque o retorno do caminho feliz (o sucesso) como a última linha da função. Isso ajuda a deixar o fluxo principal claro e previsível. Quem lê sabe que, se nada der errado, o sucesso acontece no final.

Separe partes da lógica em funções auxiliares para que as funções principais fiquem curtas, claras e fáceis de entender. Funções muito longas e cheias de detalhes dificultam a leitura e a manutenção.

Se você tem blocos de código muito grandes e indentados (por exemplo, dentro de um if, for ou switch), considere extrair esse bloco para uma nova função. Isso ajuda a manter a função principal mais plana, legível e fácil de seguir, evitando profundidade excessiva e “efeito escada” no código.

Em resumo, cuidar da legibilidade do código é essencial para manter modelos mentais claros. Práticas como alinhar o caminho feliz, evitar aninhamentos profundos e extrair funções tornam o código mais fácil de entender, manter e evoluir.

Referências:

HARSANYI, Teiva. 100 Go mistakes and how to avoid them. Shelter Island: Manning, 2022.

RYER, Mat. Code: Align the happy path to the left edge. 2016. Disponível em: https://medium.com/@matryer/line-of-sight-in-code-186dd7cdea88. Acesso em: 05 jul. 2025.

Escopo de variável é o espaço do código onde uma variável pode ser utilizada.

No Go, variáveis declaradas no nível de pacote podem ser usadas dentro de funções do mesmo pacote. Variáveis declaradas dentro de uma função podem ser usadas dentro de blocos de decisão (if) e de repetição (for).

Porém, uma variável de um escopo mais externo (como o nível de pacote ou função) pode ser redeclarada em escopos internos, causando o sombreamento de variável. Isso pode gerar confusão e bugs.

No exemplo abaixo, a variável debugMode é redeclarada dentro da função com o operador de declaração curto (:=), criando uma nova variável local e não alterando a variável do pacote como esperado:

Outro caso é quando usamos o operador de declaração curto (:=) dentro de um bloco if com múltiplos retornos de uma função. No exemplo abaixo, a variável foo é redeclarada dentro do if, sombreando a variável do nível da função e deixando a variável original inalterada:

Para evitar esse problema, a variável de erro deve ser declarada antes do retorno da função e o operador de atribuição simples (=) deve ser utilizado para modificar a variável existente, assim:

Em resumo, o sombreamento acontece quando uma variável é redeclarada em um escopo mais interno, escondendo a original. Para evitar erros, use o operador de atribuição (=) para atribuir valores a variáveis já declaradas e evite redeclarar variáveis com o mesmo nome em escopos próximos.