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

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

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

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

マルチプルゴー

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

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

結論

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

Goでコードを適切にコメントすると、https://godoc.org/golang.org/x/tools/cmd/godoc [Godoc]ツールを使用できるようになります。 Godocは、コードからコメントを抽出し、Goプログラムのドキュメントを生成するツールです。