レビューをよくするようになって何年か経つのですが、よく目にするのが1つの関数とかファイルの行数が長くて何をしてるのか把握が難しい状態です。
この場合は必要な処理が書かれているか初見では判断できないのでリファクタリングが必要だということで、次のようなステップでコメントをしています。
1. どこがどういう処理をしているのか説明をお願いする
コード自体が長くなっているときは実装した本人もどこが何のための処理なのか曖昧なことが多いので、まず説明をお願いしています。
説明がうまくいかない場合はこちらから「こういうことですか?」と質問したりしますが、こちらがわかっていてもいきなり答えを出したりしないで実装した側が説明できるようにしています。
レビュイーがこの辺をわかっているはず、という場合はこのステップは省いています。
2. その説明に沿って関数を分けてもらう
説明してもらった内容で処理のまとまりを考えてもらって関数化してもらいます。
このとき関数名で処理内容を説明できるようにしてもらいます。
ここでの認識違いが出ることはあまり無い印象ですが、お互い分け方に悩むような場合もたまにあります。
3. 各関数が長すぎないか確認する
同じ様に、分割した関数についても長くないか見直します。
1とか2に戻って繰り返すイメージになりますが、あまり修正を繰り返すと実装する側のメンタル面がしんどくなるので2回も3回も繰り返さないように多少先回りしてコメントするようにしています。
4. 各関数の処理が要求仕様と合っているか確認する
ここまで来てようやく要求仕様と実装がずれていないか確認できる状態になります。
もちろん手前までである程度状況は把握できているはずですが、最終確認をここでするようにします。
まとめ
長くなりがちなコードはある程度の塊の処理がいくつも続いていることが多いので、関数に分けてその名前で処理内容を説明させるようにし、各関数がコンパクトになるようにします。
4が本来の目的であって「仕様と実装が合ってるか」を確認したいのですが、コードが長くて読み解くのが困難な場合は確認すること自体も間違いやすいので段階を踏んでリファクタリングしてもらうようにしています。