Comentários em

Sobre Comentários

Os comentários permitem que você deixe anotações no código sem afetar a forma como ele é executado. Um comentário de uma linha começa com // em qualquer ponto da linha. O compilador ignora tudo a partir do // até o final dessa linha. Quando um comentário vem depois do código na mesma linha, ele costuma ser chamado de comentário inline. Um comentário de várias linhas começa com /* e termina com */ em qualquer ponto de uma linha. O compilador ignora tudo o que está entre eles, ao longo de 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 têm propósitos diferentes dependendo de onde aparecem.

Comentários de código

Os comentários de código explicam por que algo é feito, e não o que é feito. Use-os quando o motivo por trás de uma decisão não for óbvio no código:

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

Na maioria dos casos, um código bem escrito se explica por si só, e os comentários não são necessá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 servem para documentar um pacote, uma variável ou uma função. Essa documentação é destinada a outras pessoas que programam e que querem saber como usar seu código. Ela deve explicar, em alto nível, o que o código faz e como usá-lo. Ela não deve incluir detalhes de como o código em si funciona. Os comentários de documentação ficam diretamente antes de uma declaração, sem nenhuma linha em branco separando o comentário da declaração. O godoc analisa esses comentários para gerar a documentação do pacote, como você vê em pkg.go.dev. Um comentário de documentação deve ser uma frase completa, começando com o nome do identificador e terminando 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 seus argumentos e valores de retorno:

// 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, consulte o guia de documentação do Go.