Comment écrire des commentaires dans Go

introduction

Les commentaires sont des lignes qui existent dans les programmes informatiques et qui sont ignorées par les compilateurs et les interprètes. L'inclusion de commentaires dans les programmes rend le code plus lisible pour les humains car il fournit des informations ou des explications sur ce que fait chaque partie d'un programme.

En fonction de l'objectif de votre programme, les commentaires peuvent vous servir de notes ou de rappels, ou ils peuvent être écrits dans l'intention que d'autres programmeurs puissent comprendre ce que fait votre code.

En général, c'est une bonne idée d'écrire des commentaires pendant que vous écrivez ou mettez à jour un programme, car il est facile d'oublier votre processus de pensée plus tard, et les commentaires écrits plus tard peuvent être moins utiles à long terme.

Les commentaires dans Go commencent par un ensemble de barres obliques (//) et continuent jusqu'à la fin de la ligne. Il est idiomatique de laisser un espace blanc après la série de barres obliques.

Généralement, les commentaires ressemblent à ceci:

// This is a comment

Les commentaires ne s'exécutent pas, il n'y aura donc aucune indication de commentaire lors de l'exécution d'un programme. Les commentaires sont dans le code source pour les humains à lire, pas pour les ordinateurs à exécuter.

Dans un programme «Hello, World!», Un commentaire peut ressembler à ceci:

hello.go

package main

import (
    "fmt"
)

func main() {
    // Print “Hello, World!” to console
    fmt.Println("Hello, World!")
}

Dans une bouclefor qui itère sur une tranche, les commentaires peuvent ressembler à ceci:

sharks.go

package main

import (
    "fmt"
)

func main() {
    // Define sharks variable as a slice of strings
    sharks := []string{"hammerhead", "great white", "dogfish", "frilled", "bullhead", "requiem"}

    // For loop that iterates over sharks list and prints each string item
    for _, shark := range sharks {
        fmt.Println(shark)
    }
}

Les commentaires doivent être faits avec le même retrait que le code qu’il commente. Autrement dit, une définition de fonction sans retrait comporterait un commentaire sans retrait, et chaque niveau de retrait suivant aurait des commentaires alignés sur le code qu'elle commente.

Par exemple, voici comment la fonctionmain est commentée, avec des commentaires après chaque niveau de retrait du code:

color.go

package main

import "fmt"

const favColor string = "blue"

func main() {
    var guess string
    // Create an input loop
    for {
        // Ask the user to guess my favorite color
        fmt.Println("Guess my favorite color:")
        // Try to read a line of input from the user. Print out the error 0
        if _, err := fmt.Scanln(&guess); err != nil {
            fmt.Printf("%s\n", err)
            return
        }
        // Did they guess the correct color?
        if favColor == guess {
            // They guessed it!
            fmt.Printf("%q is my favorite color!\n", favColor)
            return
        }
        // Wrong! Have them guess again.
        fmt.Printf("Sorry, %q is not my favorite color. Guess again.\n", guess)
    }
}

Les commentaires sont faits pour aider les programmeurs, que ce soit le programmeur d'origine ou une autre personne utilisant ou collaborant dans le projet. Si les commentaires ne peuvent pas être correctement gérés et mis à jour avec la base de code, il est préférable de ne pas inclure de commentaire plutôt que d'écrire un commentaire qui contredit ou contredira le code.

Lorsque vous commentez du code, vous devriez chercher à répondre auxwhy derrière le code par opposition auxwhat ouhow. À moins que le code ne soit particulièrement délicat, regarder le code peut généralement répondre auxwhat ouhow, c'est pourquoi les commentaires sont généralement concentrés autour deswhy.

Les commentaires de blocage peuvent être utilisés pour expliquer un code plus complexe ou un code que le lecteur ne devrait pas connaître.

Vous pouvez créer des commentaires de blocage de deux manières dans Go. La première consiste à utiliser un ensemble de doubles barres obliques et à les répéter pour chaque ligne.

// First line of a block comment
// Second line of a block comment

La seconde consiste à utiliser des balises d'ouverture (/*) et des balises de fermeture (*/). Pour documenter le code, il est considéré comme idiomatique de toujours utiliser la syntaxe//. Vous utiliseriez uniquement la syntaxe/* ... */ pour le débogage, que nous aborderons plus loin dans cet article.

/*
Everything here
will be considered
a block comment
*/

Dans cet exemple, le commentaire de bloc définit ce qui se passe dans la fonctionMustGet():

function.go

// MustGet will retrieve a url and return the body of the page.
// If Get encounters any errors, it will panic.
func MustGet(url string) string {
    resp, err := http.Get(url)
    if err != nil {
        panic(err)
    }

    // don't forget to close the body
    defer resp.Body.Close()
    var body []byte
    if body, err = ioutil.ReadAll(resp.Body); err != nil {
        panic(err)
    }
    return string(body)
}

Il est courant de voir les commentaires de bloc au début des fonctions exportées dans Go; Ces commentaires sont également ce qui génère votre documentation de code. Les commentaires de bloc sont également utilisés lorsque les opérations sont moins simples et exigent par conséquent une explication approfondie. À l'exception des fonctions de documentation, évitez de trop commenter le code et faites confiance aux autres programmeurs pour comprendre Go, sauf si vous écrivez pour un public particulier.

Les commentaires en ligne apparaissent sur la même ligne d'une instruction, à la suite du code lui-même. Comme d’autres commentaires, ils commencent par une série de barres obliques. Encore une fois, il n’est pas nécessaire de laisser un espace après les barres obliques, mais il est considéré comme idiomatique de le faire.

Généralement, les commentaires en ligne ressemblent à ceci:

[code]  // Inline comment about the code

Les commentaires en ligne doivent être utilisés avec parcimonie, mais ils peuvent être efficaces pour expliquer des parties de code difficiles ou non évidentes. Ils peuvent également être utiles si vous pensez ne pas vous souvenir d’une ligne du code que vous écrivez à l’avenir ou si vous collaborez avec une personne que vous connaissez ne connaissez peut-être pas tous les aspects du code.

Par exemple, si vous n’utilisez pas beaucoup de mathématiques dans vos programmes Go, vous ou vos collaborateurs pouvez ne pas savoir que ce qui suit crée un nombre complexe. Vous souhaiterez donc peut-être inclure un commentaire en ligne à ce sujet:

z := x % 2  // Get the modulus of x

Vous pouvez également utiliser des commentaires en ligne pour expliquer la raison pour laquelle vous faites quelque chose ou pour fournir des informations supplémentaires, comme dans:

x := 8  // Initialize x with an arbitrary number

Vous ne devez utiliser les commentaires en ligne que lorsque cela est nécessaire et qu'ils peuvent fournir des conseils utiles à la personne qui lit le programme.

En plus d'utiliser les commentaires comme moyen de documenter le code, vous pouvez également utiliser des balises d'ouverture (/*) et des balises de fermeture (*/) pour créer un commentaire de bloc. Cela vous permet de commenter le code que vous ne voulez pas exécuter pendant que vous testez ou déboguez un programme que vous êtes en train de créer. C'est-à-dire que lorsque vous rencontrez des erreurs après avoir implémenté de nouvelles lignes de code, vous pouvez en commenter quelques-unes pour voir si vous pouvez résoudre le problème en question.

L'utilisation des balises/* et*/ peut également vous permettre d'essayer des alternatives pendant que vous déterminez comment configurer votre code. Vous pouvez également utiliser des commentaires de blocage pour commenter le code qui échoue pendant que vous continuez à travailler sur d'autres parties de votre code.

multiply.go

// Function to add two numbers
func addTwoNumbers(x, y int) int {
    sum := x + y
    return sum
}

// Function to multiply two numbers
func multiplyTwoNumbers(x, y int) int {
    product := x * y
    return product
}

func main() {
    /*
        In this example, we're commenting out the addTwoNumbers
        function because it is failing, therefore preventing it from executing.
        Only the multiplyTwoNumbers function will run

        a := addTwoNumbers(3, 5)
        fmt.Println(a)

    */

    m := multiplyTwoNumbers(5, 9)
    fmt.Println(m)
}

[.note] #Note: Le commentaire du code ne doit être fait qu'à des fins de test. Ne laissez pas d'extraits de code commenté dans votre programme final.
#

Commenter du code avec les balises/* et*/ peut vous permettre d'essayer différentes méthodes de programmation et vous aider à trouver la source d'une erreur en commentant et en exécutant systématiquement des parties d'un programme.

Conclusion

L'utilisation de commentaires dans vos programmes Go contribue à améliorer la lisibilité de vos programmes pour les humains, y compris votre avenir. L'ajout de commentaires appropriés, pertinents et utiles, facilitera la collaboration d'autres personnes avec vous sur des projets de programmation et rendra la valeur de votre code plus évidente.

Commenter correctement votre code dans Go vous permettra également d'utiliser l'outilGodoc. Godoc est un outil qui va extraire les commentaires de votre code et générer de la documentation pour votre programme Go.

TOC

Comment écrire des commentaires dans Go

introduction

Conclusion

Related