Goでコメントを書く方法

前書き

コメントは、コンパイラーおよびインタープリターによって無視されるコンピュータープログラムに存在する行です。プログラムにコメントを含めると、プログラムの各部分が何をしているかについての情報または説明が提供されるため、人間にとってコードが読みやすくなります。

プログラムの目的に応じて、コメントは自分自身やリマインダーへのメモとして機能したり、他のプログラマーがコードの実行内容を理解できるように作成したりできます。

一般的に、プログラムの作成中または更新中にコメントを書くことは、後で思考プロセスを忘れやすいため、良いアイデアです。また、後で書いたコメントは、長期的にはあまり役に立たない可能性があります。

Goのコメントは、スラッシュ（//）のセットで始まり、行の終わりまで続きます。一連のスラッシュの後に空白を入れるのは慣用的です。

通常、コメントは次のようになります。

// This is a comment

コメントは実行されないため、プログラムの実行時にコメントが表示されることはありません。コメントは、コンピューターが実行するのではなく、人間が読むためのソースコードにあります。

「Hello、World！」プログラムでは、コメントは次のようになります。

hello.go

package main

import (
    "fmt"
)

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

スライスを反復処理するforループでは、コメントは次のようになります。

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

コメントは、コメントしているコードと同じインデントで行う必要があります。つまり、インデントのない関数定義にはインデントのないコメントがあり、それに続く各インデントレベルにはコメントしているコードに合わせたコメントがあります。

たとえば、main関数にコメントを付ける方法を次に示します。コメントは、コードの各インデントレベルの後にあります。

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

コメントは、元のプログラマであろうと、プロジェクトで使用または共同作業しているプログラマであろうと、プログラマを支援するために作成されます。コメントをコードベースと共に適切に維持および更新できない場合は、コードと矛盾する、または矛盾するコメントを書くよりも、コメントを含めない方が良いでしょう。

コードにコメントを付けるときは、whatまたはhowではなく、コードの背後にあるwhyに答えることを検討する必要があります。コードが特にトリッキーでない限り、コードを見ると一般にwhatまたはhowに答えることができます。そのため、コメントは通常whyに集中します。

ブロックコメントを使用すると、より複雑なコードや、読者がなじみのないコードを説明できます。

Goでは、ブロックコメントを2つの方法で作成できます。最初の方法は、一連の二重スラッシュを使用して、行ごとに繰り返すことです。

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

2つ目は、開始タグ（/*）と終了タグ（*/）を使用することです。コードを文書化する場合、常に//構文を使用するのは慣用句と見なされます。デバッグには/* ... */構文のみを使用します。これについては、この記事の後半で説明します。

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

この例では、ブロックコメントはMustGet()関数で何が起こっているかを定義します。

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

Goでは、エクスポートされた関数の先頭にブロックコメントが表示されるのが一般的です。これらのコメントは、コードドキュメントを生成するものでもあります。ブロックコメントは、操作がそれほど単純ではないため、詳細な説明が必要な場合にも使用されます。関数のドキュメント化を除き、特定の対象者向けに作成している場合を除き、コードの過剰なコメントを避け、他のプログラマーにGoの理解を信頼させるようにしてください。

インラインコメントは、コード自体に続いて、ステートメントの同じ行で発生します。他のコメントと同様に、それらは一連のスラッシュで始まります。繰り返しますが、スラッシュの後に空白を入れる必要はありませんが、そうすることは慣用的であると考えられます。

一般に、インラインコメントは次のようになります。

[code]  // Inline comment about the code

インラインコメントは控えめに使用する必要がありますが、コードのトリッキーな部分や非自明な部分の説明には効果的です。また、将来書いているコードの行を覚えていないかもしれないと思う場合、またはコードのすべての側面に精通していないかもしれない知っている誰かと協力している場合にも役立ちます。

たとえば、Goプログラムで多くの数学を使用しない場合、あなたや共同編集者は、次のコードが複素数を作成することを知らない可能性があるため、そのことに関するインラインコメントを含めることができます。

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

次のように、インラインコメントを使用して、何かを行う背後にある理由を説明したり、追加情報を提供したりすることもできます。

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

インラインコメントは、必要な場合と、プログラムを読んでいる人に役立つガイダンスを提供できる場合にのみ使用してください。

コードを文書化する方法としてコメントを使用することに加えて、開始タグ（/*）と終了タグ（*/）を使用してブロックコメントを作成することもできます。これにより、現在作成中のプログラムをテストまたはデバッグしているときに実行したくないコードをコメント化できます。つまり、新しいコード行を実装した後にエラーが発生した場合、それらのいくつかをコメントアウトして、正確な問題をトラブルシューティングできるかどうかを確認できます。

/*タグと*/タグを使用すると、コードの設定方法を決定する際に別の方法を試すこともできます。また、ブロックコメントを使用して、コードの他の部分で作業を続けている間に失敗したコードをコメント化することもできます。

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：コードのコメントアウトは、テスト目的でのみ行う必要があります。コメントアウトされたコードのスニペットを最終プログラムに残さないでください。
＃

/*タグと*/タグを使用してコードをコメントアウトすると、さまざまなプログラミング方法を試すことができ、プログラムの一部を体系的にコメントアウトして実行することでエラーの原因を見つけることができます。

結論

Goプログラム内でコメントを使用すると、将来の自分を含め、プログラムを人間にとって読みやすくするのに役立ちます。関連性があり有用な適切なコメントを追加すると、他の人がプログラミングプロジェクトであなたと協力しやすくなり、コードの価値がより明確になります。

Goでコードに適切にコメントを付けると、Godocツールを使用することもできます。 Godocは、コードからコメントを抽出し、Goプログラムのドキュメントを生成するツールです。

TOC

Goでコメントを書く方法

前書き

結論

Related