コードの説明はシンプルに保ってください
(akselmo.dev)- コードレビューで長い説明と大きな diff が一緒に来ると、レビュアーが核心となる 変更理由 を把握しにくくなるため、コミットメッセージ・マージリクエストの説明・コメントは簡潔であるべき
- 説明は何が変わったかよりも なぜ変えたのか に集中すべきで、多くの変更内容はコード自体から確認できる
- すべての文脈を一度に盛り込もうとする長い説明は、一部のレビュアーの集中力とレビュー速度を下げる可能性がある
- マージレビューでは 原子的なコミット が特に重要であり、小さな修正は
git amend、マージ前の整理は rebase や squash で対応できる - LLM ツールを使うとしても、コメント・説明・コミットメッセージは自分で書いたほうが、コード理解とレビューのしやすさにより役立つ
レビュー説明は「何」より「なぜ」に集中
- コードレビューで説明、コミット、マージリクエストが 過剰な情報 で埋まると、レビュー負荷が大きくなる
- 変更内容を長々と列挙するより、重要なのは なぜ変更したのか を明確に書くこと
- コード自体がほとんどの変更内容を示せるし、不足する文脈はレビュアーが質問できる
- 長文のように書かれた説明は、集中しづらい人にとってレビューをさらに遅くする可能性がある
- コミットメッセージ、マージリクエストの説明、コードコメントは、明確で要点中心に必要な情報だけを含めるのがよい
コミット整理と LLM 利用についての要望
- コミットはマージレビューで特に 原子的 であるべきで、各変更は独立して理解できる必要がある
- 小さな修正は
git amendで反映し、マージ前には rebase で整理するか squash できる - LLM ツールを使っていても、コメント、説明、コミットメッセージは自分で書くほうがよいと考えられている
- 自分で書く過程が変更内容の理解に役立つ
- 自分で書いた説明のほうがレビュアーにとって読みやすい場合がある
- LLM ツールはできるだけ避けたほうがよいという個人的な意見も含まれている
- アクセシビリティという表現には反応もあったが、核心はコードレビューの説明をより簡潔にし、レビューしやすくしようという要望である
1件のコメント
Lobste.rsの意見
アクセシビリティ要件を特定の個人の好みと安易に同一視するのは注意が必要
ADHDだからといって長いコミットメッセージを嫌うのが普遍的なADHDの特性だとは言いにくく、アクセシビリティは「ADHDのある人が好むように何でもしてあげること」ではなく、一般の利用者に過度な負担をかけない合理的配慮に近い
だからこそ、高コントラスト、モーション軽減、ダークモードのように、個人が選べる設定の背後に多くのアクセシビリティ機能が置かれている
長いテキストの塊、たとえば小さな変更にA4二枚分の説明が付くような場合は、仕事を完全に止めてしまうことがあり、無理に読み切るとバーンアウトにつながる
「これは自分のアクセシビリティ要件であり、似た人が多いことも知っている」くらいの表現にするべきだったと思う
それでも要件ではなく好みと見ることはできるかもしれないが、LLMが作ったテキストの壁をコミットメッセージに貼り付けるときは、私のような人のことも念頭に置いてほしいというお願い
アクセシビリティの面でも、この調整の恩恵は誰もが受けるのだから、あえて反対する理由はないように見える
アクセシビリティが高まれば、同じスタートラインに立つためにその機能が必須ではない人も一緒に利益を得るので、その方向に進むのは良いことだ
AI以前からずっと過度に詳細なコメントを好んでいて、一緒に働いた人たちの中には驚く人も多かった
たとえばこのメソッドがある: https://github.com/ghostty-org/ghostty/…
この15年間、言語を問わずだいたいこのスタイルで書いてきたし、AI時代にはこの方針をAGENTS.mdにも明記している
リンク先のファイルとコメントはすべて人間が書いたもので、AIは一切使っていない
理由は単純で、コメントとコードが互いに一致しなければならないという二重記入ルールを強制できるから
両者が一致しなければ、コメントが間違っているか、コードが間違っているか、あるいは両方が間違っているわけで、「どちらが正しいのか？」と問うだけで多くの問題を見つけられた
結局のところ、自分のプロジェクトなら各自が好きなようにコメントを書けばいいと思う
後でコードを読み返すときに、そのとき下した局所的な判断の文脈を保存してくれるし、レビュアーや初見の人が文脈を積み上げる助けにもなる
こうしたコメントは冗長ではあっても、記事でいう「不要な詳細」ではなく、共有された例は「何をではなく、なぜを説明せよ」という格言の良い例だと思う
例のように、macOSユーザーが
~/.bash_profileにシェル設定を書き、ログインシェルであることを期待するようになった理由を説明するコメントは、特定の決定をなぜ行ったのかという有用な文脈を提供しているただ、LLMの話に戻ると、個人的にはまだその品質のLLM生成コメントを見たことがない
たいていは
foo()をする、次にbar()をする、最後にbazをするといった具合に、コードを読めば明らかな内容を繰り返すだけにとどまる問題なのは、ごく小さな変更にも巨大な表や箇条書きの一覧を付ける混乱ぶりだ
コミットメッセージはコードと常に同じ時点の記録として残るが、コメントは時間が経つにつれてずれていくことがあると感じる
職場でPRテンプレートに「この変更の動機と、レビューで見てほしい重要な設計上の決定を自分の言葉で説明してください」と丁寧に書いてみた
ところが10回中9回は、そのとき使っているLLMがテンプレート全体を吹き飛ばし、追加したテスト数や通過チェックボックス、些末な内容の長い枝葉まで含んだ長文の説明を吐き出してくる
おかげでレビューがとても楽しくなる
誰がLLM生成コミットメッセージツールをあちこちに入れるのが良い考えだと思ったのかは知らないが、結局コミットの中で https://noslopgrenade.com/ の問題が起きる
コミットメッセージやプルリクエストの説明には、変更の動機、設計判断、根拠といった有用な文脈がなく、コードを読めば分かる実装の詳細を段落で言い換えただけのものに変質してしまう
agents.mdに「コミットメッセージを書くときはcommit-messages.mdを参照すること」と追加する案を考えているcommit-messages.mdには、通過/失敗テストのチェックボックス禁止、個別テストの列挙ではなく要約するか、あるいはまったく書かない、といったコミットメッセージの指針を入れればよさそう自分が何をしているかをコメントに書くのは、なぜそうしているかではなく、そのやり方が正しいのか確信が持てないときだけ
繰り返し苦痛を生む代表例は正規表現
すべてをしっかり説明しなければならないときもあるが、最近は変数名の変更のような小さな変更にまで巨大な説明が付いているのを見る
興味深いことに、私はむしろコミットメッセージが短すぎるとよく言われてきた
だからclaudeがコメントを絶対に書かないよう設定した。自分で手動で98%を消し、残りの2%も書き直していたからだ
通常は非常に説明的なコミットメッセージが好きだが、ニュース記事型の構成のように、最も重要な情報を先に置き、重要度は下がるが依然として関連のある詳細を後ろに配置するほうである
たとえばタイトルには最も重要な情報をできるだけ高密度に入れ、最初の段落では変更内容をそれほど圧縮しない文で説明し、後ろの段落には、コード変更の性質を本当に理解しにくいのでなければ詳しく読む必要のない追加の詳細を置く
コミットメッセージが将来コードを読む人にとってどれほど重要かは、過小評価されているように思う
コードベースを掘り下げていて、あるブロックがなぜああなっているのか気になったとき、
git blameの先に、一見雑に見えるやり方が実はより良さそうに見えたが不完全だった複数のアプローチを経た末に残った選択だったことを、執拗なほど詳しく説明したコミットメッセージがあると、がっかりしたことはない筆者の要点に戻ると、コミュニケーションに明示的な標識を入れるのは良い調整であり、一般的にも有用である
コミットメッセージの途中に「このコードをレビューしているなら、ここで読むのをやめてもよい」のような文を入れられる
「不要な詳細は必要になったら聞けばよい」というのは、その人がずっとそばにいると大胆に仮定している
10年以上前のFLOSSコードベースに貢献し始めてから、コミットメッセージを熱心に書くようになった
なぜコードがそのように存在するのかをさらに知る唯一の方法は git 考古学であり、Emacs の
vc-annonateを覚えて簡単に追跡できるようにした仕事のコードでも、私が保守しているコードベースの元の作者がすでにずっと前に去っていたことが何度もあった
コミットメッセージはレビュー中にだけ読まれるものではなく、実際、多くのレビュー UI はコミットメッセージを隠している
問題は長文のコミットメッセージそのものではなく、下手に書かれたコミットメッセージに近いように見える
「コミットメッセージ、マージリクエストの説明、コードコメントは明確に、要点に向けて必要ベースで書き、何をしたかではなくなぜしたかを説明せよ」という指針は良さそうに見える
以前は
Fix Bugz 🚀️とだけ書いていた人が、今度は「ベストプラクティス」に従うと言って LLM でコミットメッセージを書くようになるのが問題なのかもしれない私の仮説では、ほとんどの人がコミットメッセージを書かない理由は読まれないからであり、読まれない理由は GitHub の Web インターフェースのような場所に依存してコミットを眺めるため、探しに行くための起動エネルギーが高いからである
情報が重要なら、コメントとして残すかコミットメッセージに追加できる
KDE は数年前から GitLab を使っている
長期的に見て、後世の人との成功した git 考古学 のためにはバランスが必要である
人員の入れ替わりや、文脈が頭の中から消えてしまうことのせいで、後になってその不要に見えた詳細を尋ねられないことが多い
その文脈を記録する最良の時点は、まだ持っているときである
本当に望ましいのは、重要な詳細を先に置き、概要のように明確に区分するやり方なのかもしれない
PR やコード説明は、何をしたかのためではなく なぜしたか のためのものである
コードがなぜこのような形になっているのかと、その背景にある理由を伝えるべきである
これはレビューにも良く、後で git の履歴からコードがなぜそうなったのかを探すのにも良い
コード説明を単純に保つのは重要である
理解できない、あるいは集中できないものは読めないからである
同時に、ソフトウェアを開発していると多くの文脈が失われ、今ではその文脈が作者やその人と話したことのある人、あるいはコードを深く見た人の頭の中にしかないことが多い
しかしその文脈は、コードとより強く結び付けられるべきであって、弱く結び付けるべきではないと思う
作者といつでも話せるわけではないので、常にアクセスでき、コードと一緒に更新される場所に書いておくべきである
現在のほとんどの開発フローでは、そのために最も適した場所は git のコミットメッセージである
一番上に要約を書くのは良いが、コード変更についての追加説明も残すことを勧める
今は重要に見えない内容まで文脈を外に出しておけば、未来の自分が感謝するだろう
将来的には、そうした文脈をコミットメッセージにだけ入れるやり方よりも、もっと良いアプローチが必要であり、だから個人的には、コードの「何」と「なぜ」を説明する空間をより多く与える 文芸的プログラミング が好きである