Comentários em

Sobre Comentários

Os comentários permitem-te deixar notas no código sem afetar a forma como é executado. Um comentário de uma linha começa com // em qualquer ponto de uma linha. O compilador ignora tudo desde // até ao fim dessa linha. Quando um comentário surge depois do código, na mesma linha, costuma ser chamado de comentário em linha. Um comentário multilinha começa com /* e termina com */ em qualquer ponto de uma linha. O compilador ignora tudo o que fica entre eles, abrangendo uma ou mais linhas.

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

Os comentários servem propósitos diferentes consoante o local onde aparecem.

Comentários de código

Os comentários de código explicam por que motivo algo é feito, não o que é feito. Usa-os quando a razão por trás de uma decisão não é óbvia a partir do código:

results = results[1:] // skipping the header row

Na maioria dos casos, o código bem escrito explica-se por si próprio e não são necessários comentários. Ocasionalmente, é necessário que o código faça algo complexo ou inesperado; esse tipo de código deve ser comentado.

Comentários de documentação

Os comentários de documentação são usados para documentar um pacote, uma variável ou uma função. Esta documentação destina-se a outros programadores que queiram saber como usar o teu código. Deve explicar, a alto nível, o que o código faz e como o usar. Não deve incluir detalhes sobre como o próprio código funciona. Os comentários de documentação ficam imediatamente antes de uma declaração, sem que uma linha em branco separe o comentário da declaração. O godoc analisa-os para gerar documentação de pacotes, como se vê em pkg.go.dev. Um comentário de documentação deve ser uma frase completa que começa com o nome do identificador e termina com um ponto final.

Os comentários de documentação em identificadores exportados (aqueles que começam com uma letra maiúscula) aparecem na documentação gerada. Os comentários de documentação em identificadores não exportados (aqueles que não começam com uma letra maiúscula) não aparecem, mas ainda podem fornecer contexto útil dentro do código.

Os comentários que documentam pacotes começam com o nome do pacote e descrevem o que o pacote faz:

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

Os comentários que documentam funções começam com o nome da função e descrevem o que a função faz, incluindo os seus argumentos e valores devolvidos:

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

Os comentários que documentam variáveis começam com o nome da variável e descrevem o que a variável representa:

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

Para a especificação completa dos comentários de documentação, consulta o guia de documentação do Go.