Aller au contenu

Documentation

Cory House

Code is like humor. When you have to explain it, it’s bad.

Comme pour la plupart des autres langages, la documentation de code Go se fait à l’aide de commentaires. Go utilise la même syntaxe que C/C++ ou Java pour les commentaires, à savoir des commentaires de lignes qui commencent par // et qui se terminent à la fin de la ligne et des commentaires de blocs délimités par les symboles /* et */.

Pour documenter du code, il est considéré comme idiomatique de toujours utiliser des commentaires de lignes (//). Les commentaires de blocs ne sont utilisés que pour ignorer une partie du code pendant le débogage.

Pour suivre les bonnes pratiques, tous les symboles exportés (ceux qui commencent par une majuscule) doivent être commentés, mais rien ne vous empêche de commenter les symboles privés.

Go propose des outils pour extraire la documentation du code et pour la publier sous la forme d’une page web, et pour que ces outils fonctionnent correctement, le commentaire doit être placé immédiatement avant le symbole, sans ligne vide entre ce dernier et le commentaire.

L’Entête de fichier

Chaque fichier devrait commencer par en entête contenant un copyright et une licence (de préférence avec la syntaxe spdx)

// Copyright (c) 2023 Haute école d'ingénierie et d'architecture de Fribourg
// SPDX-License-Identifier: Apache-2.0

Si vous souhaitez vous assurer que votre projet soit bien réutilisable par d’autres, il est important d’indiquer clairement la licence sous laquelle vous publiez votre code. Vous pouvez utiliser un outil tel que REUSE pour vous aider à respecter les bonnes pratiques en matière de licences.

Note

La spécification de REUSE demande que chaque licence soit placée dans un fichier séparé du dossier LICENSES à la racine du projet. D’autre part, les bibliothèque Go demandent un fichier unique LICENSE à la racine du projet. Le mieux est donc de placer toutes les licences dans le dossier LICENSES et de copier la licence principale dans le fichier LICENSE.

Certains prétendent que le nom de l’auteur et la date de création ne doivent pas être indiqués dans l’entête. En effet, ces informations sont données par l’outil de gestion de code source (git), mais pour ma part, je trouve intéressant de quand même les indiquer.

// Author:  Jacques Supcik <jacques.supcik@hefr.ch>
// Created: 3 Oct. 2023

Packages

Chaque package devrait avoir un commentaire introduisant le paquet. L’exemple ci-dessous documente le package path :

// Package path implements utility routines for manipulating slash-separated
// paths.
//
// The path package should only be used for paths separated by forward
// slashes, such as the paths in URLs. This package does not deal with
// Windows paths with drive letters or backslashes; to manipulate
// operating system paths, use the [path/filepath] package.
package path

Commandes

Un commentaire pour une commande est comparable à celui d’un package, mais il décrit plutôt le comportement du programme. La première phrase commence conventionnellement par le nom du programme lui-même, avec une initiale en majuscule, car il se trouve en début de la phrase. L’exemple ci-dessous documente la commande pprof :

// Pprof interprets and displays profiles of Go programs.
//
// Basic usage:
//
//  go tool pprof binary profile
//
// For detailed usage information:
//
//  go tool pprof -h
//
// For an example, see https://blog.golang.org/profiling-go-programs.
package main

Si le commentaire est très long, on peut exceptionnellement utiliser des commentaires de blocs pour documenter une commande.

Une pratique souvent observée consiste à placer cette documentation dans un fichier distinct (souvent nommé doc.go) placé dans le même dossier que la commande.

Types

Un commentaire pour un type explique ce que chaque instance de ce type représente. Par exemple :

package zip

// A Reader serves content from a ZIP archive.
type Reader struct {
    ...
}

Pour une structure avec des champs exportés, le commentaire explique la signification de chaque champ exporté. Par exemple :

package io

// A LimitedReader reads from R but limits the amount of
// data returned to just N bytes. Each call to Read
// updates N to reflect the new amount remaining.
// Read returns EOF when N <= 0.
type LimitedReader struct {
    R   Reader // underlying reader
    N   int64  // max bytes remaining
}

Fonctions

Le commentaire d’une fonction explique ce que la fonction fait et ce qu’elle retourne. Les arguments peuvent être mentionnés directement dans le commentaire, sans devoir utiliser une syntaxe spéciale. La première phrase du commentaire commence conventionnellement par le nom de la fonction. Par exemple :

package strconv

// Quote returns a double-quoted Go string literal representing s.
// The returned string uses Go escape sequences (\t, \n, \xFF, \u0100)
// for control characters and non-printable characters as defined by IsPrint.
func Quote(s string) string {
    ...
}

Constantes

La syntaxe de Go permet de factoriser les déclarations de constantes. Dans ce cas, un seul commentaire peut introduire un groupe de constantes liées :

package scanner

// The result of Scan is one of these tokens or a Unicode character.
const (
    EOF = -(iota + 1)
    Ident
    Int
    Float
    Char
    ...
)

Parfois, ce n’est pas le groupe, mais chaque constante qui est commentée :

package unicode

const (
    MaxRune         = '\U0010FFFF' // maximum valid Unicode code point.
    ReplacementChar = '\uFFFD'     // represents invalid code points.
    MaxASCII        = '\u007F'     // maximum ASCII value.
    MaxLatin1       = '\u00FF'     // maximum Latin-1 value.
)

Variables

La règle pour documenter les variables est semblable à celle des constantes. Voici un exemple qui documente un groupe de variables :

package fs

// Generic file system errors.
// Errors returned by file systems can be tested against these errors
// using errors.Is.
var (
    ErrInvalid    = errInvalid()    // "invalid argument"
    ErrPermission = errPermission() // "permission denied"
    ErrExist      = errExist()      // "file already exists"
    ErrNotExist   = errNotExist()   // "file does not exist"
    ErrClosed     = errClosed()     // "file already closed"
)

Note

Pour plus de détails concernant les commentaires en Go, en particulier pour la syntaxe utilisable dans les commentaires, veuillez consulter la documentation correspondante.

go doc

La commande go doc permet d’afficher la documentation intégrée dans le code.

Appelée sans argument, la commande go doc affiche la documentation du package contenu dans le répertoire courant.

Avec un seul argument, vous pouvez obtenir la documentation de n’importe quel élément. Par exemple go doc path vous donne la documentation du package path et go doc path.Match vous propose la documentation de la fonction Match du package path.

On peut aussi utiliser la go doc avec deux arguments. Dans ce cas, le premier argument indique le package et le deuxième indique le symbole pour lequel on souhaite la documentation : go doc path Match (ou go doc path match).

Tapez la commande go help doc pour une documentation complète de la commande go doc.

godoc

Godoc (en un seul mot) est un outil supplémentaire qui permet de générer une documentation en HTML. Pour installer godoc, tapez la commande suivante :

go install golang.org/x/tools/cmd/godoc@latest

Note

La commande go install installe le binaire dans le dossier $GOPATH/bin ou dans $HOME/go/bin si la variable d’environnement GOPATH n’est pas définie. Assurez-vous de mettre ce dossier dans votre PATH pour exécuter ces programmes directement.

Vous pouvez aussi demander à go install de mettre les exécutables dans un autre dossier avec la variable d’environnement GOBIN. Par exemple, pour installer godoc dans $HOME/bin, vous pouvez taper :

GOBIN=$HOME/bin go install golang.org/x/tools/cmd/godoc@latest

La commande godoc démarre un serveur web à l’adresse http://localhost:6060. Vous pouvez changer le port avec l’option -http. Par exemple godoc -http localhost:8080.

Vous pouvez aussi lancer un playground intégré grâce à l’option -play. La commande godoc help vous donnera tous les détails.

Une fois le serveur démarré, ouvrez l’URL avec votre navigateur préféré et vous pouvez consulter toute la documentation. Ça vous permet d’avoir accès à cette dernière sans devoir être connecté à Internet.

pkg.go.dev

Si vous hébergez votre code Go sur un dépôt public (Github.com, Gitlab.com, ou même le Gitlab de l’école si le projet est public), alors vous pouvez publier sa documentation sur pkg.go.dev. Consultez la documentation pour savoir comment publier votre documentation… c’est vraiment très simple !