Python、クラスや関数へのコメントの書き方

Pythonに限らず、ソースコードにコメントを書くことはよく行われます。
特に、モジュールやクラス、関数等へのコメントは
・どんな処理をするのか
・どんな引数を取るのか
・どんな値を返すのか
といったことがソースコードを読み解かなくてもわかるようになる為、できるだけ書くように推奨されています。

仕事では勿論ですが、趣味等であってもこれらのコメントを書く癖をつけることで、保守や拡張がしやすくなります。
理想としては、中身の処理を見なくても何をしているのかが把握でき、かつ、外部からそれらの関数やクラスを利用できることが目標です。

Pythonでは、ある決まった書き方をしたコメントは「ドキュメンテーション文字列」「ドックストリング」等と呼ばれ、特別に扱われます。
例えばですが…

mydoc.py

"""docstringの説明用モジュール"""

class MyDate():
    """日付を便利に扱うクラス"""

    def get_today(self):
        """現在の日付を返します"""

       何かしらの処理

このようなモジュールやクラス・関数のすぐ下で、文字を「”””」で囲むことでドックストリングとして扱われます。
このドックストリングは、プログラム中から参照することが可能で、
今回の例では、以下のように参照ができます。

help(MyDate)

Help on class MyDate in module __main__:

class MyDate(builtins.object)
 |  日付を便利に扱うクラス
 |  
 |  Methods defined here:
 |  
 |  get_today(self)
 |      現在の日付を返します
...
...

インタラクティブシェルにて、クラスや関数の動きを試したり、テストする際にこのhelp関数はよく使用します。

内部的な話をすると、このソースコード上に書いたコメントは
オブジェクトの__doc__という属性に格納されます。例えばですが、

print(MyDate.__doc__)

とすると、

日付を便利に扱うクラス

と表示されます。これはIDEやエディタの機能ではなく、Python自体の機能となっています。

この機能を利用し、Sphinx等のドキュメントビルドツールではにはAPIドキュメントの自動生成などを行っています。
ドックストリングを綺麗に書いていればそれだけでAPIドキュメントが作成できてしまうので、是非書く癖をつけましょう。

ドックストリングには、大まかな書き方のルールがあり、PEP257で定義されています。
その中から、大雑把に内容を説明します。
全体的な指針としては、シンプルで簡潔に書かれたものが好ましいです。

モジュール
モジュールドックストリングは、モジュールの内容を紹介するもので、重要なクラスや関数を見つけるための出発点になります。
1行目にはモジュールの目的を書き、それ以降に知っておくべき詳細や、メインとなるクラス、関数について紹介していきます。

クラス
1行目には、クラスの目的を記述します。それ以降には、重要なメソッドなどを紹介していき、
そのクラスをサブクラス化する上での注意点や、子クラスからアクセスして欲しくない属性などについても触れましょう。

関数
1行目には、関数が何をするか、について簡潔に書き、それ以降に振る舞いや引数、戻り値について書きます。

引数を持たず、単純な値を返す場合は、1行で簡潔に書きます。
先ほどのget_todayメソッドであれば、
「現在の日付を返す」
で充分でしょう。

戻り値を特に返さないならば、戻り値については触れないでおきましょう。
return なし
のようには、基本的には書きません。

シンプルすぎるのは勿論ですが、冗長な説明も好まれないため、綺麗なコメントを書くの中々大変です。
初めは、とりあえず全て1行程度で簡潔に書いておき、ちょっと説明が足りないな、と思ったら付け足していくぐらいでも良いでしょう。