Dica rápida: 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.

Golang

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:

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!

Cesar Gimenes

LEIA TAMBÉM

• Unix Domain Socket com Golang
• PostgreSQL via SSL com Golang