Referências nos comentários com Golang
Uma dica rápida sobre comentários em Go é incluir referências neles. Coloque o elemento que deseja referenciar entre colchetes ([ e ]), funciona com tudo que pode ser referenciado, como variáveis, constantes, funções, etc.
Veja o exemplo:
package main
import (
"fmt"
"time"
)
// pi representa a constante matemática Pi
const pi = 3.14159
// CalcularArea calcula a área de um círculo dado o raio.
// Utiliza a constante [pi] para o cálculo.
func CalcularArea(raio float64) float64 {
return pi * raio * raio
}
func main() {
raio := 5.0
area := CalcularArea(raio)
fmt.Printf(
"A área do círculo com raio %.2f é %.2f\n",
raio,
area,
)
/*
Formatos úteis:
[time.DateTime]
[time.Kitchen]
[time.RFC3339Nano]
[time.RFC3339]
*/
fmt.Println(time.Now().Format(time.DateTime))
}
No Neovim, coloque o cursor entre os colchetes e pressione Ctrl-] para ir até a definição do elemento referenciado. Para voltar, pressione Ctrl-t. No VSCode, use a extensão Go to Definition para realizar a mesma ação.
Comentários e qualquer tipo de documentação frequentemente ficam desatualizados. O esforço para mantê-los atualizados é tão grande quanto o de manter o código. Uma piada antiga é que documentação é uma mentira prestes a acontecer.
A melhor documentação é o próprio código. Nomes bons e descritivos são melhores que comentários.
Você não deve evitar escrever documentação, mas mantenha-a em uma quantidade gerenciável e nos pontos realmente relevantes. Criar referências nos comentários facilita a navegação no código e adiciona utilidade e contexto para quem está lendo.
Vídeo com a demonstração:
Até a próxima!