同僚が書いた Go初学者へのコードレビューでよくあったコメント20選 では、Go初学者へのコードレビューでよくあったコメント20選を紹介しました。
今回は私が コードレビューでよくお願いするコメント追加のお願い について紹介します。
前提：コメントを書いて欲しいわけ
コードレビューでコメントを書いて欲しい理由は以下の通りです。
- プロダクト、サービスの持続可能な開発を支えるため
- 人が入れ替わっても開発の迷いを可能な限り減らすため
具体的なコメントの追加パターン
①変数やパラメーターの説明を書く
コードを書く人にとっては必要があって構造体や変数を定義しているので自明ですが、第三者からすると解釈に悩むことがあります。
そのため誰が見ても自明でしょうという変数以外については注釈をいれます。
たとえば、User 構造体における ID は自明（どのような採番ルールか？みたいな疑問は出るが、ID を入力している処理見ればわかるので困らない）なのでコメントは不要です。
type User struct {
// ここは自明なのでいらない
// 人によっては UUIDv4 ですとか書くかも
id string
}
しかし、以下のような構造体の場合は、ConditionKey1 が何を表しているのかがわかりにくいです。
そのため、コメントを追加してあげると良いです。
type Event struct {
...
// 条件達成のために必要な条件
// 条件が存在しない場合は、空文字列となります
// ConditionThreshold はこの値以上である場合条件達成となります
ConditionKey1 WinnerEventConditionKey
ConditionThreshold1 int64
ConditionKey2 WinnerEventConditionKey
ConditionThreshold2 int64
}
②複雑な処理や関数の説明を書く
コードはできるだけシンプルに書くべきですが、どうしても複雑な処理は出ます。
そのコードを読む時の負荷が高い場合には、コメントで簡単に動きをまとめてもらいます。
ただ細かく書きすぎると、コードのメンテの時にコメントもたくさん直さないといけないのでバランスが大事です。
// この関数は、データを複数のステージで並列処理し、
// パフォーマンスを向上させるよう最適化されています。
// 1. データをキューに投入する
// 2. 複数のワーカーで処理を分散させる
// 3. 結果を統合して返す
func processConcurrently(data []Item) []Result {
...
}
※この例は責務が多すぎる関数になっていますが、コメントの書き方を参考にしてください。
③一見してなぜその処理が入ってるかわからない場合は補足する
- なんかわからないけど通信してるとか、
- なんかわからないけどメモリ操作してるとか
なんて処理ありますよね？
一見するとわかりませんが、必ずそれをやっている理由が必ずあるはずです。
後世の人が困らないように理由を書いておいてあげましょう。
// バッファをクリアする理由:
// ここでメモリリークを防ぐため、定期的にクリアしています。
// 過去にメモリ使用量が増大した問題があったため、この処理が追加されました。
buffer.Clear()
④利用時の注意事項を書く
関数やメソッド自体を利用する場合、前提条件があったり、想定した責務を持っていない場合があります。
名前でそれを悟らせるのが有効ではありますが、できないときもあるのでその時はコメントで補足します。
// str には ASCII 文字のみが使われていることを前提としています
// そのため、この関数の利用時には事前に不要な文字を削除してください
func convert(str string) string {
...
}
※これは例なので validate いれればいいじゃんはいわないでください😗
⑤マジック変数の値の説明を書く
// xxx という処理で待機する最大の秒数
const MaxIntervalSeconds = 10
このような定数があった場合、このコメントでは不十分です。
なぜなら、今後この定数をいじる必要があった時の情報が欠落しているためです。
そのため以下のように背景や、いつならいじって良いのか、なぜ今この値を設定したのかを書くとわかりやすいです。
// xxx という処理で待機する最大の秒数
//
// 例1: 2024/11/14時点では暫定的に10秒にしているが、タイムアウトが頻発するようなら伸ばすこと
// 例2: 負荷テスト(100rps程度)の結果算出した値、伸ばす場合は xxx を考慮すること
// see: https://....
// 例3: 10未満にはしないこと。なぜなら〜。
const MaxIntervalSeconds = 10
⑥公式ドキュメントやリファレンス、議論へのリンクを貼る
場合によってはニッチなファイルスキーマやプロトコルなどを使うことがあります。
また、そのパーサーを書く時もあるでしょう。
開発した人はドキュメントを探し出し実装しますが、次の人が同じ資料を探すのは時間がかかります。
必ず参照資料をコメントに載せるようにしましょう。
// この関数は XXX ファイルフォーマットをパースします。
// 詳細は以下のリンクを参照してください: https://www.example.com/xxx-format
func parseXXX(file string) ([]string, error) {
...
}
また、自分たちのチーム内で議論があった場合もリンクを貼ると良いでしょう。
⑦オプショナルな引数を渡す場合は、なぜ渡しているかを書く
func hoge(flag bool, opts ...Option) {
...
}
のような関数があった時に通常はそのままですが、
hoge(true)
明確に xxx というオプションを渡す時は（自明の場合を除き）そのオプションを渡す理由をコメントします。
このようにしておくと、あとでこのオプションが不要になった時に削除しやすくなりまし、コードを流用するときもわかりやすくなります。
// xxx では TLS に対応していないため、TLS を無効にしています
hoge(true, WithoutTLS())
まとめ
コードレビューでコメントを書いて欲しい理由と、具体的なコメントの追加パターンを紹介しました。コメントを書くことで、プロダクト、サービスの持続可能な開発を支えるため、人が入れ替わっても開発の迷いを可能な限り減らすために重要です。
後世の人（自分含む）が困らないようになると良いですね！！
他にもコメントの追加パターンがあれば教えてください🙇♂️
Discussion