小さな変更をレビューする

自動車部品メーカーの社内システムのチームに入って2週間です。先輩から「この変更、レビューしてもらえますか」と頼まれました。

変更は20行ほどです。何を見て、どう書けばよいのでしょうか。経験が浅くても、役に立つレビューはできます。見る場所と書き方が決まっているからです。

レビューで最初に見るのは名前です。コードは書く時間より、読まれる時間のほうがずっと長いからです。

f(n, x) では、何をする関数か、読む人にはわかりません。certificate_fee(copies, unit_price) なら、説明がなくても伝わります。

名前を変えても、動きは同じです。読みやすさだけが良くなります。

# 市役所の窓口システムに、同僚が足した関数です。
def f(n, x):
    return n * x


print(f(3, 300))

# この f, n, x を、何をするかがわかる名前に変えてください。
# 住民票の写しは1通300円です。n は通数、x は1通の値段です。
# 名前を変えたら、もう一度実行して、結果が同じか確かめます。

次に、ふつうでない入力を考えます。空のリスト、0、マイナスの数、とても大きな数などです。

書いた人は、ふつうの入力でしか試していないことが多いです。レビューする人が「データがない日はどうなりますか」と聞くと、本番の前にバグが見つかります。

動かせるなら、自分でその入力を試してみます。

def average_wait(minutes):
    # 窓口の待ち時間の平均を、分で返します。
    return sum(minutes) // len(minutes)


print("午前の平均:", average_wait([12, 8, 15, 5]), "分")

# 祝日の振替で、窓口を開けなかった日があります。
# 下の行の先頭の # を消して実行し、何が起きるかを見てください。
# print("休みの日の平均:", average_wait([]), "分")

良いレビューコメントには、三つのことが入っています。どこの話か、何が問題か、どうすれば良くなるか、です。

「わかりにくい」だけでは、書いた人は何を直せばよいかわかりません。「3行目の x は、unit_price にすると意味が伝わります」なら、すぐ直せます。

自信がないときは、質問の形で書きます。