コード/テストコード/コミットログ/コードコメント には何を書くべきか
この記事は最終更新日から5年以上が経過しています。
を受けて考えたことを纏める
概要
コーディングをする際に書く以下の4つに対して、それぞれ何のために何を書くべきか
- コード
- テストコード
- コミットログ
- コードコメント
前提
コード/テストコード/コミットログ/コードコメント は書く時間より読まれる時間のほうが長い そのため、書く時間を節約できるから手を抜くという理論は通用しない 読む人間は未来の自分かもしれない（というかその可能性が高い）ので、先のことを考えて書くべき
コードには How
How を書こうと意識することは無い コードには How しか書けないという認識を持つことが大事
テストコードには What
テストコードはテスト対象コードの仕様になる そのため仕様は何であるか、つまり What を意識して書くのが大事
良い例
- テスト対象の仕様を先に決めてテストから書く
悪い例
- カバレッジを上げるためだけに何のテストかわからないけど TestError001 とかを作ってしまう
コミットログには Why
コードやテストコードから読み取れないものがある
それはなぜその変更をしているのかという情報 -> Why
Why つまり問題認識を共有出来てないと、 What や How が正しいのかどうかわからない
良い例
- XXXという変数がこれこれこういう誤解を招いたためより意味のある名前に変更する
- hogehogeというサードパーティモジュールにはこういう脆弱性があるので脆弱性がないものに変更
- fugafugaというメソッドは非推奨になったので推奨されるメソッドに変更
悪い例
- 指摘対応 / レビュー対応 / レビュー指摘を修正
「怒られたのでやめます」ぐらいな感じ、当事者意識がない。 理由がわからないまま or 納得できないまま 修正するのは危険。レビュアーと議論したほうがいい。
- バグ修正
せめてどこかに詳細へのリンクがあるならいいが… コミット単位ではバグの原因を噛み砕いてもっと細かく Why を書けるはず
- Lint対応
「先生に怒られたので変更しました」と言われてる感じ。 なぜ指摘がでたか理解してないとまた同じ指摘を受けることになる 中にはLinterのバグで対応しなくていいが、指摘が出るものもあるので理解しないで指摘を消そうとするのは危険
- 新規作成 / 新規追加
リポジトリ作った最初のコミットならわからないでもない ただ、それ以外でクラスやメソッド、ファイルなどを追加したならなにか理由があるはず 新規だから雑に書いていいということはない
- yyyymmdd 作業中断するため一旦コミット
最も意味がないコミットログ コミットログは作業記録をつける場所じゃなくて、コードの変更履歴を残す場所
コードコメントには Why not
ここでいうコードコメントは JavaDoc などのドキュメンテーション用のコメントは含まない
あくまで、コード上のコメントの話
他にも書くことあるという意見は当然あるが、いちばん重要なのは Why not
Why What How から現状は読み取れるが、実装中の葛藤は読み取れない
こうすることも出来るはずがだなぜやってないか、という情報が残ってないとリファクタリングされてバグを踏んだりする
コードコメントにはなぜやってないか Why not つまり「言い訳」を書くのが最重要
良い例
- ここは XXX を使うべきだが、hogehogeの理由で仕方なく YYY を使っている。解決のための issue は これ
- fugafuga の処理もこのトランザクションに含めるべきだがそうするとロールバック時に ZZZ という問題が起きるので別にしている
悪い例
- 何をしているかを書く
- どういう処理かを書く
- なぜやっているかを書く(これは場合による日本語のなぜには Why not を含む場合があるため)