10:コメントには「なぜ」を書く

プログラムの コメント には何を書いていますか？　コメントを書くときにも、抑えておくべきポイントがあります。

具体的な失敗

def do_something(users):
    # ～～をする処理
    # usersにはUserのQuerySetを受け取る

    # 引数のusersを1つひとつループして処理をする
    # usersがループするときにバックエンドにSQLが実行される
    for user in users:
        ...
    return users  # SQLはループでの1回しか実行されない

このプログラムには無駄なコメントが多いのが問題です。 プログラムを読めば、処理は理解できます。コメントがないと理解しにくいコードの場合、コメントで説明を補う前に簡単なコードに書き直せないか考えてみましょう。

ベストプラクティス

コメントには「なぜ」を書きましょう。 関数の仕様を書く場合はコメントでなく、docstringに書きましょう。

def do_something(users):
    """ ～～をする処理

    複数のユーザーに対して <do_something> を行う。
    ～～の場合に～～なので、ユーザーのデータを変更する必要がある。
    """
    # SQLの実行回数を減らすために、このループは別関数に分離せずに処理する
    for user in users:
        ...
    return users

コードを読むだけでは理解しにくいプログラムの場合、処理の意味と、なぜそう書くのか をコメントに書きましょう。

コメントは 「なぜこう処理しないのか」の説明 と考えても良いでしょう。 プログラムを読んだ人が「当たり前に考えた」ときに違和感があるような処理に「なぜこのような処理をしているのか」を注釈する場合などに使うと効果的です。

（中略）詳細は書籍 自走プログラマー をご参照ください