第103条
小さな変更
レビューに出す変更が大きいほど、一行ずつは丁寧に読まれなくなる。欠陥はすり抜け、最初に見てもらうまでの待ちも長くなる。
心得
一度に読み切れる大きさで変更を出す
どうするか
変更は一つで完結するものにする。100行くらいならたいてい妥当で、1000行はたいてい大きすぎる。ただし最後はレビュアーが決める。リファクタリングは振る舞いの変更と別に出し、依存し合う変更は一つにまとめず、順番に積んで出す。名前の変更や生成コードのような機械的な変更を、行数を合わせるためだけに割ることはしない。レビュアーが全体として何をするのか見えなくなるほど、設計を細かく切り分けることもしない。
なぜ起きるか
レビュアーの注意には限りがある。SmartBear が Cisco で 2,500件のレビューを調べた研究では、200行未満のレビューは比較的高い率で欠陥を見つけ、それを超えると結果は大きく落ちた。著者たちは、それより大きいとレビュアーは手に負えなくなり、欠陥は見つからないと結論している。Google のガイドは時間の取り方の面を挙げる。大きな変更一つのために30分のまとまった時間を空けるより、小さな変更のために5分を何度か見つけるほうがレビュアーには楽だ。Google では変更の行数の中央値は24行で、最初のフィードバックまでの待ち時間の中央値は、小さな変更で1時間未満、とても大きな変更で約5時間だった。
当てはまらなくなるとき
変更ごとの固定費：変更には大きさに関係なくかかる固定費がある（レビューの往復、CI の実行、レビュアーの頭の切り替え）。細かく割るほどその費用と待ちが増える。レビューが遅い場では、依存し合う小さな変更を順に通すほうが、まとまった一つの変更より取り込みまでずっと時間がかかることがある。
出典
Google「Small CLs」『Google Engineering Practices Documentation』。"100 lines is usually a reasonable size for a CL, and 1000 lines is usually too large, but it’s up to the judgment of your reviewer." SmartBear Software「Code Review at Cisco Systems」、『Best Kept Secrets of Peer Code Review』(Smart Bear, 2006) 所収。2,500件のレビューを扱ったベンダー自身の事例研究で、"LOC under review should be under 200, not to exceed 400." と勧めている。変更の大きさとレビュー待ちの数字は Caitlin Sadowski, Emma Söderberg, Luke Church, Michal Sipko & Alberto Bacchelli『Modern Code Review: A Case Study at Google』(ICSE-SEIP, 2018) による。変更ごとの固定費というカウンターは DORA「Working in small batches」(dora.dev) による。"One reason work is done in large batches is because of the large fixed cost of handing off changes."
原典を読む引用するとき
コラムで読む
- AI がコードを書くとき コラムの次：ブランドリーニの法則
関連する法則
- 86コードの健全性を上げるなら承認するすべての変更に完璧を求めるとレビューが遅くなり、遅いレビューはコードベースを良くするどころか悪くする。
- 29ボーイスカウトの規則コードが劣化するのは、片付けが、めったに実施されないリファクタリングに先送りされがちだからだ。
- 35リーナスの法則一人では見つからないバグも、同じコードを見る別の人にはあっさり分かることが多い。
- 37リトルの法則安定した系では、系の中にある件数の平均は、到着率と平均滞在時間の積に等しい。
- 102自動化バイアス自動化された補助を使う人は、自分で確かめる代わりにそれを頼りがちだ。補助が指摘しないものを見落とし、補助が間違っていてもそれに従う。