リポジトリをぼっち*1でメンテしていくにあたって、心強い味方は実装当時の自分自身のコメントだと思う。 それを実装する必要があったのは何故か、実装時に考えたこと、本当はこうしたかったけど制約で出来なかった、実装Bは何故却下したか...など、色々なことを書き残している。GitHubを使っているので、書き残し方法としてはPullRequestのコメントとして入れていた。
しかし、GitHubのblameから簡単に辿れるのはコミットメッセージだけである。 コミットのハッシュ値を検索にかけて過去のPullRequestを発掘してくるという方法もあるが、結構探すときに労力がかかることに最近気づいた。
Web上をうろうろしていた時に見かけた、コメントの残し方に関する意見*2 にも、GitHubに内容を残すリスクとして他サービスに移行した場合に失われてしまうという話があった。とても納得した。 以降は、これまで利用頻度が低かったgit commitをより意識して情報を残していこうと考えている。
今の所、次のようにTPOに応じて適宜使い分ける予定。
- ソースコードのコメント: 実際の仕様の説明
- 超重要な実装上の仕様。メソッドの使い方、引数の意図、などを書く。
- 将来修正されるべきものについてTODOコメントなども書く。
- コミットコメント: 機能単位の変更理由の説明
- 1機能/1commit を守って積み上げ、機能の意図や変更理由を記録する。
- 1PullRequestが複数のcommitで構成されることも当然ある。
- GitHub上のコメント: 特定の問題の解決の瞬間にだけ必要とされたこと
- リリース前後で気になって調べたこと、書き込み当時のサービス状況。
- 考えた結果ボツにした実装案とその理由。
参考
