はじめに
前の演習では、Goでコメントを書く方法が2つあることを学びました。//を行の先頭に付ける1行コメントと、/*と*/で囲む複数行のコメントブロックです。
ドキュメントコメント
Goでは、コメントはコードを文書化するうえで重要な役割を果たします。
これらのコメントはgodocコマンドによって抽出され、Goパッケージに関するドキュメントを作成するために使われます。
ドキュメントコメントは、説明する対象の名前で始まり、ピリオドで終わる完全な文にします。
コメントは、パッケージのほか、エクスポートされた識別子、たとえばエクスポートされた関数、メソッド、パッケージ変数、定数、構造体の前に書きます。これらの詳しい説明は、今後の演習で学びます。
パッケージレベルの変数は、次のように書きます。
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
パッケージコメント
パッケージコメントは、パッケージ句（package x）の直前に書き、次のようにPackage x ...で始めます。
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
関数コメント
関数コメントは、関数宣言の直前に書きます。
関数名で始まる完全な文にします。
たとえば、関数Calculateのエクスポートされたコメントは、Calculate ...という形にします。
また、その関数がどんな引数を受け取るのか、受け取った引数をどう扱うのか、戻り値が何を意味するのかも説明し、最後はピリオドで終わります。
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
説明
Goblinocusは、天気予報をとても真剣に受け止めている国です。
評判が高く、責任感のある、熟練したエンジニアなので、Goblinocusのさまざまな都市の現在の天気を予報するプログラムを書いてほしいと、彼らに頼まれました。
当時は忙しかったので、代わりに友人の一人にその仕事を頼みました。
しばらくして、Goblinocusの大統領から連絡があり、友人のコードが理解できないと言われました。
コードを確認してみると、友人は責任あるプログラマーとして行動しておらず、コードにはコメントが1つもないことがわかりました。
ゴブリンたちにもわかるように、プログラムを明確に説明する義務を感じています。
1. package weatherのドキュメントを書く
ゴブリンたちはあまり賢くないので、このパッケージが自分たちのために何をしてくれるのかを忘れてしまいました。
その内容を説明するコメントをpackage weatherに書いてください。
パッケージのコメントでは、パッケージを紹介し、パッケージ全体に関係する情報を書くようにしましょう。
2. 変数CurrentConditionとCurrentLocationのドキュメントを書く
Goblinocusの大統領は少し疑り深く、コメントのない変数が国を滅ぼすために使われているのではないかと恐れています。
パッケージ変数CurrentConditionとCurrentLocationの使われ方を明確にして、大統領を安心させてください。
これによって、パッケージを使う人なら誰でも、これらの変数にどんな情報が保存されているのか、その情報で何ができるのかがわかるようになります。
3. Forecast()関数のドキュメントを書く
Goblinocusの予報担当者たちは、Forecast()関数が何をするのかを知りたがっています（ただし、どうやって動くのかは教えないでください。残念ながら、それで余計に混乱してしまうからです）。
この関数が何をするのかを説明するコメントを書いてください。どうやってそれをするのかは書かないでください。
学習演習
