私のいちばん好きなGitコミット（2019）

 (dhwthompson.com)
3 ポイント 投稿者 GN⁺ 2024-02-02 | 1件のコメント | WhatsAppで共有

私のいちばん好きなGitコミット

  • Gitのコミットメッセージの重要性を強調し、コードベースを文書化するうえで最も強力なツールの1つだと考えている。
  • 開発者 Dan Carley が書いた "Convert template to US-ASCII to fix error" というコミットを例に、その理由を説明している。
  • GDS（Government Digital Service）での経験を踏まえ、公開でコーディングすることの利点の1つは、こうした例を組織の外にも共有できる点だとしている。

このコミットが優れている理由

  • コミットメッセージとコード変更量の比率は面白いが、それが共有する価値がある理由ではない。
  • ほかの組織や開発者であれば、このコミットメッセージは単に change whitespace や fix bug と要約されていたかもしれない。
  • その代わりに、Dan は周囲の人たちにとって本当に役立つコミットメッセージを作るために時間をかけた。

変更理由を説明している

  • 最高のコミットメッセージは、変更した 何を だけでなく、なぜ 変更したのかも説明する。
  • このコミットでは、/etc/nginx/router_routes.conf の内容と一致させるために導入されたテストが、bundle exec rake で実行されたときに ArgumentError: invalid byte sequence in US-ASCII エラーで失敗した理由を詳しく説明している。
  • こうした情報は文書化する価値が非常に高く、人々が元の文脈を忘れたり、別のチームに移ったり、組織を離れたりする中で簡単に失われてしまう。

検索しやすい

  • コミットメッセージの冒頭には変更を引き起こしたエラーメッセージがあり、誰でもコードベースで git log --grep "invalid byte sequence" を実行したり、GitHub のコミット検索を使ったりしてこのエラーを検索できる。
  • 実際に複数の人がこの問題を検索し、以前に誰がこの問題を見つけ、どう対処したのかを突き止めることができた。

物語を伝える

  • コミットメッセージには、問題がどのように見えていたか、調査の過程がどうだったか、解決までの流れがどうだったかという詳細が含まれている。
  • コミットメッセージは、特定のファイルや関数、コード行を文書化するのではなく、コードベースがたどった道のりに関する追加情報を文書化するのに非常に向いている。

みんなを少し賢くする

  • Dan が各段階で実行したコマンドを文書化したことは、チーム内の知識を共有する軽量な方法になりうる。
  • このコミットメッセージを読むことで、誰かが Unix ツールセットに関する有用なヒントをいくつか学べるかもしれない。
  • この変更をレビューする人も、後からこのコミットを見つける人も、そうしたことを学べる。

思いやりと信頼を築く

  • 最後の段落は人間的な文脈を加えている。
  • これを読むと、Dan が巧妙なバグを追跡するのに1時間を費やしたことへの苛立ちと、それを解決した満足感の両方を感じ取れる。
  • こうしたコミットメッセージは、あらゆる変更の背後に最善の判断を下した人間がいることを思い出させてくれる。

良いコミットの重要性

  • この例は極端なケースであり、すべてのコミットにこれほどの詳細さを期待しているわけではない。
  • しかし、変更の背後にある文脈を説明し、他の人が学べるように助け、コードベースに対するチームの集合的なメンタルモデルに貢献する優れた例である。
  • 良いコミットメッセージの利点や、それをより簡単に構造化するのに役立つツールについてさらに知りたいなら、Joel Chippindale の "Telling stories through your commits" と Tekin Süleyman の "A branch in time" を勧める。

GN⁺の見解

  • この記事は Git コミットメッセージの重要性を強調し、コードベースの歴史を文書化して知識を共有するうえで、コミットメッセージがいかに強力なツールになりうるかを示している。
  • Dan Carley のコミットメッセージは、変更理由、検索性、物語性、知識共有、思いやりと信頼の構築など、さまざまな面で模範的な事例を示している。
  • 良いコミットメッセージを書く重要性を理解して実践することで、開発者はより良い協業とコード保守を経験でき、これはチーム全体の生産性と効率の向上にもつながる。

関連記事

1件のコメント

 
GN⁺ 2024-02-02
Hacker Newsの意見

  • GitHub共同創業者の意見:

    • Gitのコミットメッセージはコードを文書化するための独特な方法だが、最適化されていない。
    • ほとんどのツールはコミットメッセージの最初の1行しか表示しない。
    • Gitは、コミットメッセージをメール本文のように、すべてのプロジェクト参加者が読めるよう設計したが、現実にはほとんど見られない。
    • git blameを使って関連するコミットメッセージを探すのも難しい。
    • Gitプロジェクトのコミットメッセージは非常に詳細だが、実際にはほとんど活用されていない。
    • Gitによる優れた文書作成は、ほとんどのコミュニティでは時間の無駄に近い。

  • 特定の問題に対するコミットメッセージの重要性:

    • 問題を明確に説明するコミットメッセージの最初の1行が重要である。
    • 必要であれば、追加情報を提供する残りの部分を読めばよい。

  • コミットメッセージに対する個人的な感情:

    • 優れたコミットメッセージを書くことに誇りはあるが、それが他人にとって価値があるのか確信が持てない。
    • ほとんどの人はコミットメッセージをほとんど検索しない。
    • 美しいコミットメッセージはプログラマーの虚栄であり、実質的な価値がないかもしれない。

  • コミットメッセージの最初の1行を書く戦略:

    • git logを使うときは最初の1行が最も重要である。
    • 最初の1行には何をしたかではなく、なぜそうしたのかを明記すべきである。
    • ニュース記事のように、重要度の高い情報から詳細な情報へ順に書いていくのがよい。

  • コミットメッセージ修正の難しさ:

    • コミットメッセージは作成後に修正しにくい。
    • .mdファイルやWiki、Confluenceなどの文書は修正が容易である。
    • コンポーネントの設計を説明したくなる誘惑は避け、必要なら文書を改善するほうがよい。

  • 小さなコミットに対する詳細な説明の重要性:

    • 小さなコミットほど、相対的に長い説明が必要になることがある。
    • 小さな変更の理由を詳しく説明することが重要である。

  • コミットメッセージの限界とツールの問題点:

    • コミットメッセージの最初の1行を、より具体的に書く必要がある。
    • 残りの長い説明には大きな価値がないかもしれない。
    • 開発ツールの問題点を指摘し、エラーメッセージはもっと明確であるべきだと述べている。
    • コード編集ツールが非標準の空白文字を許容する理由への疑問を呈している。

  • コミットメッセージよりコミット衛生の重要性:

    • コミットメッセージの詳細さよりも、良いコミット衛生のほうが重要である。
    • 整然として独立したコミットは、コードの機能を簡単に抽出して再利用できるようにする。

  • 自動スクワッシュとリベースへの批判:

    • 自動スクワッシュは意味のあるコミットメッセージ作成を妨げる。
    • リベースは開発者が意図的に整理するためのものであり、マージ時のデフォルトパターンであるべきではない。