Adicionando comentários em códigos feitos com GoLang

Adicionando comentários em códigos feitos com GoLang

Durante a sua jornada como desenvolvedor GoLang, em alguns momentos, você irá se deparar com alguns pedaços de códigos que possuem comentários atribuídos a eles, como é o caso destes aqui:

package main

//Importação da biblioteca fmt.
import "fmt"

func main() {
	// Mensagem de boas vindas no console
	fmt.Println("Hello, World!")
}

Um comentário nada mais é do que um texto que possui o objetivo de informar de forma simples e direta o que está acontecendo naquela linha de código.

Muitos comentários estão atrelados a funções, variáveis ou até a lógicas inteiras, e possuem o intuito de informar outros desenvolvedores sobre o propósito e funcionamento de determinados trechos do código.

Os comentários são especialmente úteis para facilitar a manutenção do software, ajudando a equipe de desenvolvimento a compreender rapidamente a lógica implementada, evitando interpretações erradas ou perda de tempo tentando decifrar trechos mais complexos.

Nesta lição, você aprenderá tudo o que precisa saber sobre como criar comentários em seus códigos feitos com GoLang.

Comentários e a sua influência durante a performance das suas aplicações

Diferente do que você pode estar pensando, os comentários não são interpretados pelo compilador e não afetam a performance da aplicação.

O que acontece é que o compilador do Go, simplesmente ignora os comentários, pois eles existem apenas para documentação e leitura humana.

Sendo assim, quando o Go executa seu código na memoria ou gera um arquivo binário, todos os comentários que você fez, são automaticamente apagados da versão compilada.

O que acontece caso meu código tiver mais de 1000 linhas de comentários?

Bem, se o seu código possui tantos comentários assim, talvez você esteja comentando ele do jeito errado.

Porque primeiro, diversos comentários no código poderão impactar seriamente a legibilidade do código por outros desenvolvedores.

O que consequentemente impacta no tamanho do arquivo que contém toda a lógica do seu código (o arquivo final compilado, não vai com esses comentários).

E por último, e não menos importante... convenhamos que se o seu arquivo possui mais de 1000 linhas de comentários atrelados a eles... não era mais fácil criar uma documentação separada? 😅

A ideia desta lição, não é só te ensinar a como criar comentários em seus projetos feitos com GoLang, mas também te instruir a como criar comentários concisos e autoexplicativos.

Mas primeiro, você precisa saber como criar comentários, e quais tipos de comentários a linguagem suporta, vamos nessa?

Criando comentários em GoLang

É verdade que a maioria das linguagens de programação aceitam comentários, e o caso do GoLang não é uma exceção.

No caso do Go, existem três tipos de comentários principais.

1️⃣ Ordinary Comments (Comentários Comuns)

São os comentários padrões, mais utilizados na linguagem, e se você está comigo desde o início desta jornada, já deve ter se deparado com algum deles.

// Este é um comentário de exemplo!

Comentários comuns, podem conter uma única linha, ou podem ser compostos de múltiplas linhas, por exemplo:

// Este é um comentário de uma única linha

/*
   Este é um comentário de múltiplas linhas.
   Ele pode ser usado para explicar um bloco maior de código.
*/

No caso dos comentários de uma única linha, adicionamos o // antes de qualquer texto.

Já nos comentários de múltiplas linhas, todo o texto deve ser descrito dentro das tags /* */.

Vejamos um exemplo desses dois tipos de comentários em ação:

// Este é um comentário do arquivo main.go
//  - vai mostrar uma mensagem de boas vindas
//   - Vai terminar a execução do programa

package main

//Aqui estamos fazendo a importação dos nossos módulos...
import (
	"fmt"
)

func main() {
	/*
          Função principal da minha aplicação, aqui iremos mostrar a mensagem de boas vindas...
          A mensagem será "Olá Mundo!"
        */

        fmt.Println("Olá, Mundo!");
}

//Daqui pra baixo não tem mais nada...

Fácil, não? 🙃

2️⃣ Godoc Comments (Comentários de documentação)

Além dos comentários normais, temos os comentários de documentação, que são e deverão ser usados para documentar pacotes, funções, structs e variáveis de forma padronizada.

O Godoc é uma ferramenta oficial de documentação do GoLang. Ele extrai informações dos comentários do código e os organiza de forma estruturada.

É importante ressaltar que o GoDoc já vem embutido na instalação do Go. Ou seja, você não precisa baixar nada extra para usá-lo.

Para que ele funcione corretamente, os comentários devem seguir um formato específico, começando com o nome do elemento documentado e sendo escritos em frases completas.

Vamos ver alguns exemplos:

// Pacote calculadora fornece funções matemáticas básicas.
package calculadora

// Soma retorna a soma de dois números inteiros.
func Soma(a, b int) int {
    return a + b
}

Vamos ver algumas regras:

✅ Sempre começam com o nome do elemento que estão documentando.

✅ Devem ser frases completas e diretas.

Para visualizar a documentação gerada, basta digitar o seguinte comando no seu terminal (certifique-se de que você está dentro da pasta do projeto):

go doc calculadora.Soma

Para ver a documentação de um pacote inteiro, basta digitar o seguinte comando no terminal:

go doc calculadora

Se você deseja visualizar a documentação de forma mais amigável, pode rodar um servidor local usando o seguinte comando no terminal:

godoc -http=:6060

Depois, acesse http://localhost:6060/pkg/ no navegador para ver a documentação formatada.

3️⃣ General Compiler Directives (Diretivas do compilador)

Estes representam tipos de comentários especiais que são usados para passar instruções ao compilador ou ao linker.

Tais comentários sempre começam com //go: e são utilizados para otimizações ou configurações específicas, vamos ver um exemplo:

//go:noinline

func exemploFuncao() {
    // Essa função não será inline pelo compilador
}

Vejamos outro exemplo para inclusão de arquivos específicos:

//go:build linux
package main

É importante ressaltar que diferente do GoDoc, essas diretivas não aparecem na documentação do GoDoc, mas podem ser visualizadas no código-fonte ou analisadas por ferramentas especializadas.

Para saber mais sobre o funcionamento, consulte a documentação da ferramenta.

Escrevendo comentários melhores

Comentários são fundamentais para tornar o seu código mais compreensível e fácil de manter. Pensando nisso, separamos algumas dicas para você 🤓

✅ Comente o "por quê", não apenas o "o quê"

Se você é um desenvolvedor organizado e se preocupa com a legibilidade do seu código, é bem provável que seu código já nos dê uma ideia do que está sendo feito, então foque em explicar o por que algo foi implementado daquela forma.

🔴 Ruim (repetitivo e óbvio):

x := x + 1 // Incrementa x em 1

🟢 Bom (explica o motivo da lógica):

x := x + 1 // Ajuste para lidar com índice baseado em zero

✅ Escreva comentários como se estivesse explicando para outra pessoa

Sim, seus comentários precisam ser claros e totalmente diretos ao ponto que se propõe a explicar. Um exercício muito bom, é você pensar que você está escrevendo para outro desenvolvedor entender.

🔴 Ruim (vago e genérico):

// Ajusta o valor
valor := calcularImposto(total)

🟢 Bom (específico e útil):

// Aplica a alíquota de imposto conforme a legislação vigente
valor := calcularImposto(total)

✅ Use comentários de documentação (GoDoc) para APIs públicas

Se sua função ou pacote for usado por outros desenvolvedores, eu recomendo que você documente corretamente usando o GoDoc.

🔴 Ruim (sem contexto para quem usa a função):

func Soma(a, b int) int {
    return a + b
}

🟢 Bom (documentado corretamente):

// Soma retorna a soma de dois números inteiros.
// Útil para operações matemáticas básicas.
func Soma(a, b int) int {
    return a + b
}

📌 Não se esqueça de que você pode rodar go doc NomeDaFuncao no terminal para ver essa documentação!

✅ 4. Evite excesso de comentários desnecessários

Não comente coisas óbvias, até porque se o seu código for autoexplicativo, não precisa de comentário 😆

🔴 Ruim (óbvio e polui o código):

// Define uma variável chamada idade e atribui o valor 30
idade := 30

🟢 Bom (sem comentário desnecessário):

idade := 30

✅ Use comentários para explicar decisões complexas

Se você tomou uma decisão não tão óbvia no código, é de vital importância que você a explique.

🔴 Ruim (o código não deixa claro a decisão tomada):

timeout := 500 // Tempo de espera padrão

🟢 Bom (explica o motivo do valor escolhido):

// O timeout de 500ms foi definido após testes de desempenho com múltiplas conexões
timeout := 500

✅ Evite comentários desatualizados

Comentários que não refletem mais o código podem confundir mais do que ajudar. Sempre os atualize quando modificar o seu código.

🔴 Ruim (o comentário está incorreto):

// Converte Fahrenheit para Celsius
func converterCelsiusParaKelvin(temp float64) float64 {
    return temp + 273.15 // Na verdade, converte para Kelvin
}

🟢 Bom (comentário correto):

// Converte Celsius para Kelvin
func converterCelsiusParaKelvin(temp float64) float64 {
    return temp + 273.15
}

✅ Use diretivas do compilador com cautela

Comentários especiais como //go:noinline devem ser usados apenas quando necessário e explicados.

🔴 Ruim (usa diretiva sem explicação):

//go:noinline
func calcular() { ... }

🟢 Bom (explica o motivo da diretiva):

//go:noinline
// Evitamos inline para manter o desempenho consistente em processadores diferentes.
func calcular() { ... }

✅ Utilize separação visual em comentários longos

Se um comentário for longo, divida-o em blocos para melhorar a legibilidade.

🔴 Ruim (muito texto em uma linha só, difícil de ler):

// Esta função é usada para conectar ao servidor e deve ser chamada antes de qualquer outra operação para garantir que a conexão seja estabelecida corretamente.

🟢 Bom (mais legível e organizado):

// Conecta ao servidor antes de executar operações.
// - Garante que a conexão seja estabelecida corretamente.
// - Deve ser chamada no início do programa.

Captou todas as dicas? Não? São muitas, não é verdade? 😝

Por conta disso, fiz um resumo com todas elas abaixo:

Repositório da lição

Todos os arquivos relacionados com esta lição, podem ser encontrados nos seguintes repositórios abaixo:

Conclusão

Nesta lição, você aprendeu tudo o que precisava saber sobre como criar comentários em GoLang, e a sua importância na área de desenvolvimento de software.

Até a próxima lição 😉