Commentaires en

À propos de Commentaires

Les commentaires permettent de laisser des notes dans le code sans que cela change son exécution. Un commentaire sur une seule ligne commence par //, n'importe où sur une ligne. Le compilateur ignore tout ce qui suit // jusqu'à la fin de cette ligne. Quand un commentaire vient après du code sur la même ligne, on parle souvent de commentaire en ligne. Un commentaire multiligne commence par /* et se termine par */, n'importe où sur une ligne. Le compilateur ignore tout ce qui se trouve entre les deux, sur une ou plusieurs lignes.

// 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. */

Les commentaires ont différentes utilités selon l'endroit où ils apparaissent.

Commentaires de code

Les commentaires de code expliquent pourquoi quelque chose est fait, pas ce qui est fait. Utilise-les quand la raison derrière une décision n'est pas évidente à la lecture du code :

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

Dans la plupart des cas, un code écrit clairement se passe d'explications, et les commentaires ne sont pas nécessaires. Il arrive parfois que le code doive faire quelque chose de complexe ou d'inattendu ; ce type de code mérite un commentaire.

Commentaires de documentation

Les commentaires de documentation servent à documenter un paquet, une variable ou une fonction. Cette documentation s'adresse aux autres développeurs qui veulent savoir comment utiliser ton code. Elle doit expliquer, à un niveau général, ce que le code fait et comment l'utiliser. Elle ne doit pas entrer dans les détails de son fonctionnement interne. Un commentaire de documentation se place juste avant une déclaration, sans ligne vide entre le commentaire et la déclaration. godoc les analyse pour générer la documentation du paquet, comme on peut le voir sur pkg.go.dev. Un commentaire de documentation doit être une phrase complète qui commence par le nom de l'identifiant et se termine par un point.

Les commentaires de documentation sur les identifiants exportés (ceux qui commencent par une lettre majuscule) apparaissent dans la documentation générée. Ceux sur les identifiants non exportés (ceux qui ne commencent pas par une lettre majuscule) n'apparaissent pas, mais ils restent utiles pour donner du contexte dans le code.

Les commentaires qui documentent un paquet commencent par le nom du paquet et décrivent ce que fait le paquet :

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

Les commentaires qui documentent une fonction commencent par le nom de la fonction et décrivent ce qu'elle fait, y compris ses arguments et ses valeurs de retour :

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

Les commentaires qui documentent une variable commencent par le nom de la variable et décrivent ce que représente la variable :

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

Pour la spécification complète des commentaires de documentation, voir le guide de documentation Go.