よもやま話β版

よもやま話を書きます

コメントの残し方を方向修正した

リポジトリをぼっち*1でメンテしていくにあたって、心強い味方は実装当時の自分自身のコメントだと思う。 それを実装する必要があったのは何故か、実装時に考えたこと、本当はこうしたかったけど制約で出来なかった、実装Bは何故却下したか...など、色々なことを書き残している。GitHubを使っているので、書き残し方法としてはPullRequestのコメントとして入れていた。

しかし、GitHubのblameから簡単に辿れるのはコミットメッセージだけである。 コミットのハッシュ値を検索にかけて過去のPullRequestを発掘してくるという方法もあるが、結構探すときに労力がかかることに最近気づいた。

Web上をうろうろしていた時に見かけた、コメントの残し方に関する意見*2 にも、GitHubに内容を残すリスクとして他サービスに移行した場合に失われてしまうという話があった。とても納得した。 以降は、これまで利用頻度が低かったgit commitをより意識して情報を残していこうと考えている。

今の所、次のようにTPOに応じて適宜使い分ける予定。

  • ソースコードのコメント: 実際の仕様の説明
    • 超重要な実装上の仕様。メソッドの使い方、引数の意図、などを書く。
    • 将来修正されるべきものについてTODOコメントなども書く。
  • コミットコメント: 機能単位の変更理由の説明
    • 1機能/1commit を守って積み上げ、機能の意図や変更理由を記録する。
    • 1PullRequestが複数のcommitで構成されることも当然ある。
  • GitHub上のコメント: 特定の問題の解決の瞬間にだけ必要とされたこと
    • リリース前後で気になって調べたこと、書き込み当時のサービス状況。
    • 考えた結果ボツにした実装案とその理由。

参考

*1:2018年秋時点でエンジニアチームは1名で運用されている

*2:url失念...発見次第貼ります!