この記事はGo2 Advent Calendar 15日目の記事です。
コメントの悩み
まずは復習から。
とりあえず関数を例にします。Goでは関数などのシンボルの上に、 関数名[半角スペース]内容... という形式でコメントを書くことで、自動的に関数とコメントを紐付けてドキュメント化してくれます。複数行書くこともできます。
// Hoge reports whether the hoge is fuga.
// hogehoge. hogehoge.
func Hoge() {}
↓
便利ですね。
問題は、このコメントを日本語で書くとき起こります。
社内で使うツールなどは、分かりやすさ優先でドキュメントは日本語にすることが多いかと思います。個人的にも、そうした方がベターだと考えます。
そういったときよく見かける（自分の観測範囲内）のがこんなコメント。
// Hoge はhogeがfugaかどうかを調べる。
func Hoge() {}
先述の通り、 関数名[半角スペース]内容... というルールを守っているためドキュメント化されますが、この書き方にはいくつかの懸念があります。
- 見た目の問題: 謎のスペースが挟まっている。typoにすら見えるかもしれない。
- 言葉の問題: 主語からきっちり始めるのが読みやすいとは限らない。
仕様上、英語ほど自然に書くのは無理とはいえ、なんかすっきりしないなあ……と思っていました。（個人の感想です）
一つの解決案
そこで、自分は以下の形式で書くようにしています。
// Hoge - hogeがfugaかどうかを調べる。
func Hoge() {}
関数名の後に - を挟んでいます。特に記号にこだわりはないのですが、: などよりスペースを挟んでも違和感がないものを選定しました。
メリット：
- 少し見た目がすっきりする。（主観）
- 主語に縛られないため、日本語的に自然に書ける。（主観）
デメリット：
- 一つ余計なコーディング規約を増やしてしまう。
- 誰も使っていない書き方。
独自記法なのが心苦しいですが、今の所はこのスタイルで統一することで十分綺麗にドキュメント化できていると思っています。
何か他にいい案あれば是非コメントで教えてください！
というわけで、短いですが以上になります。ありがとうございました。