とりゅふの森

GCPデータエンジニアとして生きる

【Python入門】コメントとdocstring

f:id:true-fly:20210822190212p:plain

本日はPython入門記事です。

本日のテーマはこちら!

Pythonのコメントとdocstringを理解する

Pythonのコメントの書き方

Pythonのインラインコメントは#始まりで記述します。#以降の記述がコメントとして扱われます。

# 挨拶する
def hello(name):
    print('Hello {} !'.format(name))

では、複数行のコメント、ブロックコメントはどう記述するのでしょうか?

# 挨拶する
# 引数: name
#     挨拶する名前
def hello(name):
    print('Hello {} !'.format(name))

Javaだと/**/で囲えばブロックコメントになったりと、言語によってはインラインコメントとブロックコメントで異なる記述方法をしますが、

Pythonはブロックコメントでも、インラインコメントと同様の記述方法をします。

では、ダブルクォーテーションまたはシングルクォーテーション3つに囲まれた以下の記述方法は見たことあるでしょうか?

def hello(name):
    """挨拶する

    Args:
        name (str): 挨拶する名前
    """
    print('Hello {} !'.format(name))

ダブルクォーテーションまたはシングルクォーテーション3つに囲まれた箇所は、プログラムでは動作しないので、コメントのように定義できますが、Pythonの定義上はStr型になります。

この記述方法を、docstringと呼びます。

ダブルクォーテーション3つはコメント?

docstringでも複数行をコメントアウトするような使い方ができなくもないですが、注意が必要です。
例えば以下のようなリストの2つをコメントアウトする時に、ダブルクォーテーション3つで囲ってしまうと、囲った箇所が文字列を判定され、かつ末尾のカンマがなくなるためにエラーになります。

sample_list = [
    100,
    200,
    """
    400,
    800,
    """
    1600,
]

for v in sample_list:
    print(v)

実行結果

$ python main.py 
  File "main.py", line 8
    1600,
    ^
SyntaxError: invalid syntax
Pythonのコメントアウトは、必ず#で1行ずつコメントアウトするようにしましょう。

docstringとは

docstringはモジュール、クラス、メソッドの直下に記述します。
docstringにはGoogleスタイル、numpyスタイルなどの記述方法があります。
今回はGoogleスタイルを例に記述しています。 各スタイルの記述方法については以下の記事が参考になると思います!

qiita.com

docstringを書くメリットとして、

  • ソースコードを読んだ時にクラスやメソッドの説明があるとわかりやすい
  • VSCodeなどの統合開発環境のスニペットに説明を表示できる
  • ドキュメント生成ツールに利用ができる

などが挙げられます。

Pythonのプログラムを書くのであれば、docstringは原則記載すべきです。

docstringの書き方

以下のような、bird.pyというモジュール、クラス、メソッド全てにdocstringを記述したファイルを用意しました。

"""バードモジュール
バードクラスを定義する。
"""


class Bird:
    """バードクラス

    Note:
        バードクラス、飛べる鳥は飛べる

    Attributes
        name (str): 名前
        color (str): 色
        flyable (bool): 飛ぶことができるかどうか
    """

    def __init__(self, name, color, flyable=True):
        """初期化

        Args:
            name (str): 名前
            color (str): 色
            flyable (bool, optional): 飛ぶことができるかどうか Defaults to True.
        """
        self.name = name
        self.color = color
        self.flyable = flyable

    def fly(self):
        """飛ぶ

        Raises:
            Exception: flyableがFalseの場合、飛ぶことができない

        Returns:
            str: 飛んだことを示すメッセージ
        """
        if not self.flyable:
            raise Exception('{} cannot fly...'.format(self.name))
        return '{} fly!'.format(self.name)

まずモジュール(=ファイル名)の説明は、ファイルの先頭に記述します。このモジュール内で何が定義されているかを記述します。

"""バードモジュール
バードクラスを定義する。
"""

クラスの説明は、クラス名の下に記述します。docstringそのものはクラス内の要素であるため、インデントが必要です。

class Bird:
    """バードクラス

    Note:
        バードクラス、飛べる鳥は飛べる

    Attributes
        name (str): 名前
        color (str): 色
        flyable (bool): 飛ぶことができるかどうか
    """

メソッドの説明も、メソッド名の下にインデントして記述します。メソッドの引数、戻り値、発生する例外などを記述できます。

    def __init__(self, name, color, flyable=True):
        """初期化

        Args:
            name (str): 名前
            color (str): 色
            flyable (bool, optional): 飛ぶことができるかどうか Defaults to True.
        """

    def fly(self):
        """飛ぶ

        Raises:
            Exception: flyableがFalseの場合、飛ぶことができない

        Returns:
            str: 飛んだことを示すメッセージ
        """

Note、Attributes、Args、Returns、Raisesなどの記述方法は以下を参考に記述しましょう。

sphinxcontrib-napoleon.readthedocs.io

docstringをVSCodeで書くなら拡張機能「Python Docstring Generator」がおすすめ!

VSCodeでPythonをコーディングしているのであれば、拡張機能の「Python Docstring Generator」を利用するのがおすすめです!インストールすれば、メソッドやクラス名の下でCtrl + SHift + 2でdocstringの雛形を自動生成可能です。Googleスタイルなどのスタイルも指定できます。

marketplace.visualstudio.com

docstringとコードスニペット

これを別のPythonファイルでimportして、docstringがどのように役立つのかを見ていきましょう。

以下のPython拡張機能がインストールされている環境で検証しています。

marketplace.visualstudio.com

まずはbird.pyをimportしたとき、モジュ-ルの説明が見れます。

f:id:true-fly:20210822175849p:plain

birdモジュール内のBirdクラスを入力しようとしたとき、以下のようにスニペットにクラスに記述したdocstringが表示されます。

f:id:true-fly:20210822180330p:plain

Bird()と入力すると、__init__()のdocstringが表示されます。Argsを記述していると、入力中のパラメータの説明が上部に表示されます。

f:id:true-fly:20210822180550p:plain

インスタンスメソッドも同様にスニペットでdocstringが表示されます。

f:id:true-fly:20210822180755p:plain

以上で確認できたとおり、docstringを記述しておけば、そのモジュールを呼び出す時に、毎回定義を確認しなくてすみます。

スニペットに表示される説明文を確認するだけで、仕様を把握することができ、プログラミングのスピードも上がります!

まとめ

以上、今回はPythonのコメントとdocstringについてをまとめました。
誰が見てもわかるコメント、docstringを書くことはプログラミング上達のために欠かせない能力です。特にdocstringを簡潔に書くことができれば、メソッドやクラス分けも適切に行うことができ、読みやすいコードになると思います。

新・明解Python入門

新・明解Python入門

Amazon