docstringを書くポイント
docstringはソースコード内に書かれるドキュメントです。
他の人や数ヶ月後の自分が読んだときに助かるように書きましょう。
分かりやすく簡潔で、欲しい情報が明確なdocstringが良いです。
何をするものかを端的に書く
引数の説明を書く
返り値を書く
入出力の例を書く
副作用がある場合（関数の外に影響する場合）は明記する
たとえば、以下のような流れで書けます。
def date_range(from_date, to_date, step_days=1):
"""
{{ 一行説明 }}
{{ 説明。引数と返り値を明記すると良いです }}
>>> ... # 入出力の例
>>> ...
{{ その他注意点や副作用 }}
"""
チームによってはdocstringの書き方をルールにしていたりします。
ルールに則ってdocstringを書くと、コードのハイライトや入力補完に活用してくれるエディタや開発環境もあります。
コメントとの違い
コメントはプログラムを読む際に役に立つ説明や、コード上の意図の説明に使えます。
コードのまとまりでやろうとしてること
複雑な処理などの場合、なぜその書き方をしているのかの意図
# TODO: この書き方はバグを誘発するので良くない など、将来に残すメモ書き
docstringは対して、ドキュメントです。
Pythonファイル、関数の仕様、動作、入出力を書くものです。
コメントはコード上の書き方や意図について説明、補完するものであって、
docstringはPythonファイル、関数のあるべき姿、求められているものを書くものです。