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

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

具体的な失敗
=======================

.. code:: python

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

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

ベストプラクティス
==================

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

.. code:: python

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

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

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

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

.. omission::