Lorsque vous pensez à la programmation, il est naturel de se concentrer sur des sujets tels que les langages, les algorithmes et le débogage. Mais la documentation technique peut être tout aussi importante pour bien faire les choses.

Sans une bonne documentation, la réutilisation du code peut en souffrir. Les nouveaux utilisateurs d'une base de code peuvent facilement se perdre ou être frustrés si la documentation n'est pas à la hauteur. Il est non seulement important de comprendre ce que fait un programme, mais aussi comment, voire pourquoi, il le fait.

Des packages tels que Pydoc pour Python et Javadoc pour Java aident en automatisant une partie du processus. L'outil Godoc fait exactement la même chose pour Go.

Qu'est-ce que Godoc ?

Godoc est un package Go qui vous permet de créer, de gérer et d'utiliser la documentation Go dans « la méthode Go ». La méthode Go est un ensemble de principes que, en tant que programmeur Go, vous devez suivre pour améliorer la qualité du code.

En utilisant Godoc, vous pouvez facilement lire la documentation et le code d'autres développeurs. Vous pouvez également automatiser la création de votre propre documentation et la publier à l'aide de Godoc.

instagram viewer

Godoc est similaire à Javadoc, le documenteur de code pour Java. Ils utilisent tous les deux des commentaires et du code dans des modules pour générer de la documentation. Et les deux outils structurent cette documentation en HTML afin que vous puissiez la visualiser dans un navigateur.

Premiers pas avec Godoc

Utiliser Godoc est facile. Pour commencer, installez le package Godoc à partir du site Web de golang à l'aide de cette commande :

aller obtenir golang.org/x/tools/cmd/godoc

L'exécution de cette commande installera Godoc dans votre espace de travail spécifié. Une fois terminé, vous devriez pouvoir exécuter le godoc commande dans un terminal. S'il y a des erreurs avec votre installation, essayez de mettre à jour Go vers une version récente.

Godoc recherche des commentaires sur une ou plusieurs lignes à inclure dans la documentation qu'il génère.

Assurez-vous de formater le code de la manière Go, comme expliqué dans la publication Go Efficace par l'équipe Go pour les meilleurs résultats.

Voici un exemple utilisant des commentaires sur une seule ligne de style C++ :

// L'utilisateur est un modèle de structure contenant
taper Utilisateur structure {
}

Vous pouvez également utiliser des commentaires de bloc de style C :

/* 
L'utilisateur est une structure de données personnalisée
Vous pouvez inclure n'importe quel texte ici et le serveur Godoc le formatera lorsque vous l'exécuterez.
*/
taper Utilisateur structure {
}

Dans les commentaires ci-dessus, "User" commence les phrases car le commentaire décrit ce que fait la structure User. C'est l'un des nombreux sujets abordés par le Go way. Commencer les phrases de documentation par un nom utile est crucial puisque la première phrase apparaît dans la liste des packages.

Exécution d'un serveur Godoc

Une fois que vous avez commenté votre code, vous pouvez exécuter le godoc commande dans votre terminal, depuis le répertoire de code de votre projet.

Classiquement, les développeurs Go utilisent le port 6060 pour héberger la documentation. Voici la commande pour exécuter un serveur Godoc sur ce port :

godoc -http=:6060

La commande ci-dessus héberge votre documentation de code sur hôte local ou 127.0.0.1. Le port n'a pas à 6060; godoc fonctionnera sur n'importe quel port inoccupé. Cependant, il est toujours préférable de suivre les conventions de la documentation Go.

Une fois que vous avez exécuté la commande, vous pouvez afficher votre documentation dans un navigateur en visitant hôte local: 6060. Le temps nécessaire à Godoc pour générer votre documentation dépendra de sa taille et de sa complexité.

Le code ci-dessous adhère à la méthode Go, dans ce cas en utilisant des commentaires sur une seule ligne.

// nom du paquet
forfait utilisateur
// fmt est responsable du formatage
importer (
 "fmt"
)


// L'utilisateur est une structure de données humaines
taper Utilisateur structure {
 Âge entier
 Nom chaîne de caractères
}


fonctionprincipale() {
// human est une initialisation de la structure User
 humain := Utilisateur {
 Âge: 0,
 Nom: "personne",
 }


fmt. Println (humain. Parler())
}
// Talk est une méthode de la structure User
fonction(utilisateur récepteur)Parler()chaîne de caractères {
revenir "Chaque utilisateur peut dire quelque chose !"
}

Si vous exécutez Godoc sur le module de code ci-dessus, vous devriez voir une sortie ressemblant à ceci :

Notez qu'il est dans un format familier, similaire à ce que vous trouverez sur le site Web de documentation officielle de Go.

Godoc utilise le commentaire précédant la déclaration du package comme Aperçu. Assurez-vous que ce commentaire décrit ce que fait votre programme.

La Indice contient des liens vers les déclarations de type et les méthodes afin que vous puissiez y accéder rapidement.

Godoc fournit également une fonctionnalité permettant de visualiser le code source qui compose le package dans le Fichiers de package section.

Améliorer votre documentation avec Godoc

Vous pouvez inclure plus que du texte brut dans votre documentation Godoc. Vous pouvez ajouter des URL pour lesquelles Godoc générera des liens et structurer vos commentaires en paragraphes.

Si vous souhaitez créer un lien vers une ressource, écrivez l'URL dans votre commentaire, et Godoc le reconnaîtra et ajoutera un lien. Pour les paragraphes, laissez une ligne de commentaire vide.

// Paquet principal
forfait principale
// Document représente un document normal.
//
// Lié à https://google.com
taper Document structure {
 pages entier
 références chaîne de caractères
 signé bourdonner
}


// Write écrit un nouveau document dans le stockage
//
// Vous pouvez en apprendre davantage sur l'écriture sur Wikipedia.com
fonctionÉcrire() {
}

Notez que Godoc vous demande d'écrire les URL en entier pour qu'il puisse les lier. Dans cet exemple, l'URL Google inclut le https:// préfixe, donc Godoc ajoute un lien vers celui-ci. Étant donné que le domaine Wikipédia n'est pas une URL complète en soi, Godoc le laissera seul.

Voici quelques bons principes à appliquer lors de la documentation de votre code Go :

  • Gardez votre documentation simple et concise.
  • Commencez la phrase des fonctions, des types et des déclarations de variables par leurs noms.
  • Commencez une ligne avec un retrait pour la pré-formater en tant que code.
  • Les commentaires commençant par "BUG(nom)" comme "BUG(joe): ça ne marche pas" sont spéciaux. Godoc les reconnaîtra comme des bogues et les signalera dans leur propre section de la documentation.

Godoc peut atténuer vos problèmes de documentation

En utilisant Godoc, vous pouvez être plus productif et vous soucier moins de l'effort de documentation de vos programmes à la main.

Vous devez garder votre documentation précise, détaillée et pertinente pour faciliter la lecture et la compréhension de votre public cible. Il est également essentiel que vous teniez à jour les commentaires de code lorsque vous modifiez votre programme.

Consultez la documentation du package Godoc pour en savoir plus sur l'utilisation de Godoc.