TOC

Wie schreibe ich Kommentare in Go

Einführung

Kommentare sind Zeilen in Computerprogrammen, die von Compilern und Interpreten ignoriert werden. Durch das Einschließen von Kommentaren in Programme wird der Code für den Menschen besser lesbar, da Informationen oder Erklärungen zu den Aktionen der einzelnen Programmteile bereitgestellt werden.

Abhängig vom Zweck Ihres Programms können Kommentare als Notizen für Sie selbst oder als Erinnerung dienen, oder sie können mit der Absicht geschrieben werden, dass andere Programmierer verstehen, was Ihr Code tut.

Im Allgemeinen ist es eine gute Idee, Kommentare zu schreiben, während Sie ein Programm schreiben oder aktualisieren, da es leicht ist, Ihren Gedankenprozess später zu vergessen, und später geschriebene Kommentare können auf lange Sicht weniger nützlich sein.

Kommentare in Go beginnen mit einer Reihe von Schrägstrichen (//) und werden bis zum Ende der Zeile fortgesetzt. Es ist idiomatisch, nach den Schrägstrichen ein Leerzeichen zu setzen.

Im Allgemeinen sehen Kommentare ungefähr so ​​aus: 

// This is a comment

Kommentare werden nicht ausgeführt, daher wird beim Ausführen eines Programms kein Kommentar angezeigt. Kommentare sind im Quellcode für Menschen zum Lesen, nicht für Computer zum Ausführen.

In einem "Hallo Welt!" - Programm könnte ein Kommentar so aussehen:

hello.go

package main

import (
    "fmt"
)

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

In einerfor-Schleife, die über ein Slice iteriert, können Kommentare folgendermaßen aussehen:

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)
    }
}

Kommentare sollten im selben Einzug wie der Code erfolgen, den sie kommentieren. Das heißt, eine Funktionsdefinition ohne Einzug hätte einen Kommentar ohne Einzug, und jede folgende Einzugsebene hätte Kommentare, die an dem Code ausgerichtet sind, den sie kommentiert.

So wird beispielsweise die Funktionmainkommentiert, wobei Kommentare auf jede Einrückungsstufe des Codes folgen:

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)
    }
}

Es werden Kommentare abgegeben, um Programmierern zu helfen, unabhängig davon, ob es sich um den ursprünglichen Programmierer oder eine andere Person handelt, die das Projekt verwendet oder daran mitarbeitet. Wenn Kommentare nicht ordnungsgemäß gepflegt und zusammen mit der Codebasis aktualisiert werden können, ist es besser, keinen Kommentar einzuschließen, als einen Kommentar zu verfassen, der dem Code widerspricht oder widerspricht.

Wenn Sie Code kommentieren, sollten Sie versuchen, diewhy hinter dem Code im Gegensatz zu denwhat oderhow zu beantworten. Wenn der Code nicht besonders schwierig ist, kann das Betrachten des Codes im Allgemeinen diewhat oderhow beantworten, weshalb sich Kommentare normalerweise auf diewhy konzentrieren.

Blockkommentare können verwendet werden, um komplizierteren Code oder Code zu erklären, mit dem der Leser nicht vertraut sein dürfte.

Sie können Blockkommentare in Go auf zwei Arten erstellen. Der erste besteht darin, eine Reihe von doppelten Schrägstrichen zu verwenden und diese für jede Zeile zu wiederholen. 

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

Die zweite besteht darin, öffnende Tags (/*) und schließende Tags (*/) zu verwenden. Für die Dokumentation von Code wird es als idiomatisch angesehen, immer die Syntax von//zu verwenden. Sie würden nur die/* ... */-Syntax zum Debuggen verwenden, auf die wir später in diesem Artikel eingehen werden. 

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

In diesem Beispiel definiert der Blockkommentar, was in der FunktionMustGet() geschieht:

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)
}

Es ist üblich, Blockkommentare am Anfang der exportierten Funktionen in Go anzuzeigen. Diese Kommentare erzeugen auch Ihre Codedokumentation. Blockkommentare werden auch verwendet, wenn Operationen weniger einfach sind und daher eine gründliche Erklärung erfordern. Mit Ausnahme der Dokumentationsfunktionen sollten Sie versuchen, eine Überkommentierung des Codes zu vermeiden und darauf vertrauen, dass andere Programmierer Go verstehen, es sei denn, Sie schreiben für eine bestimmte Zielgruppe.

Inline-Kommentare werden in derselben Zeile einer Anweisung nach dem Code selbst angezeigt. Wie andere Kommentare beginnen sie mit einer Reihe von Schrägstrichen. Auch hier ist nach den Schrägstrichen kein Leerzeichen erforderlich, dies wird jedoch als idiomatisch erachtet.

Inline-Kommentare sehen im Allgemeinen so aus: 

[code]  // Inline comment about the code

Inline-Kommentare sollten sparsam verwendet werden, können jedoch zur Erklärung kniffliger oder nicht offensichtlicher Codeteile hilfreich sein. Sie können auch nützlich sein, wenn Sie der Meinung sind, dass Sie sich möglicherweise nicht mehr an eine Codezeile erinnern, die Sie in Zukunft schreiben, oder wenn Sie mit jemandem zusammenarbeiten, von dem Sie wissen, dass er nicht mit allen Aspekten des Codes vertraut ist.

Wenn Sie beispielsweise in Ihren Go-Programmen nicht viel Mathematik verwenden, wissen Sie oder Ihre Mitarbeiter möglicherweise nicht, dass Folgendes eine komplexe Zahl erstellt. Daher möchten Sie möglicherweise einen Inline-Kommentar dazu einfügen: 

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

Sie können auch Inline-Kommentare verwenden, um den Grund für eine Aktion zu erläutern, oder um zusätzliche Informationen bereitzustellen, wie in: 

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

Sie sollten Inline-Kommentare nur verwenden, wenn dies erforderlich ist und wenn sie der Person, die das Programm liest, hilfreiche Hinweise geben können.

Zusätzlich zur Verwendung von Kommentaren zum Dokumentieren von Code können Sie auch öffnende Tags (/*) und schließende Tags (*/) verwenden, um einen Blockkommentar zu erstellen. Auf diese Weise können Sie Code auskommentieren, den Sie nicht ausführen möchten, während Sie ein Programm testen oder debuggen, das Sie gerade erstellen. Das heißt, wenn nach dem Implementieren neuer Codezeilen Fehler auftreten, können Sie einige davon auskommentieren, um festzustellen, ob Sie das genaue Problem beheben können.

Mit den Tags/* und*/ können Sie auch Alternativen ausprobieren, während Sie festlegen, wie Ihr Code eingerichtet werden soll. Sie können Blockkommentare auch verwenden, um fehlgeschlagenen Code zu kommentieren, während Sie weiterhin an anderen Teilen Ihres Codes arbeiten.

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: Das Auskommentieren von Code sollte nur zu Testzwecken erfolgen. Hinterlassen Sie keine Ausschnitte aus auskommentiertem Code in Ihrem endgültigen Programm.
#

Durch Auskommentieren von Code mit den Tags/* und*/ können Sie verschiedene Programmiermethoden ausprobieren und die Fehlerquelle ermitteln, indem Sie Teile eines Programms systematisch auskommentieren und ausführen.

Fazit

Durch die Verwendung von Kommentaren in Ihren Go-Programmen können Sie die Lesbarkeit Ihrer Programme für den Menschen verbessern, einschließlich Ihres zukünftigen Selbst. Das Hinzufügen geeigneter Kommentare, die relevant und nützlich sind, kann es anderen erleichtern, bei Programmierprojekten mit Ihnen zusammenzuarbeiten, und den Wert Ihres Codes deutlicher machen.

Wenn Sie Ihren Code in Go richtig kommentieren, können Sie auch das ToolGodocverwenden. Godoc ist ein Tool, das Kommentare aus Ihrem Code extrahiert und Dokumentation für Ihr Go-Programm generiert.

Related