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つの方法でブロックコメントを作成できます。 1つ目は、スラッシュのセットを使用し、行ごとにそれらを繰り返すことです。
// 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) }
注:コードのコメントアウトは、テスト目的でのみ行う必要があります。 コメントアウトされたコードのスニペットを最終的なプログラムに残さないでください。
/*
タグと*/
タグを使用してコードをコメントアウトすると、さまざまなプログラミング方法を試すことができ、プログラムの一部を体系的にコメントアウトして実行することでエラーの原因を見つけることができます。
結論
Goプログラム内でコメントを使用すると、将来の自分自身を含め、人間がプログラムを読みやすくするのに役立ちます。 関連性があり有用な適切なコメントを追加すると、他の人がプログラミングプロジェクトであなたと協力しやすくなり、コードの価値がより明確になります。
Goでコードに適切にコメントを付けると、Godocツールを使用することもできます。 Godocは、コードからコメントを抽出し、Goプログラムのドキュメントを生成するツールです。