「コメント(#)とdocstring(""")の違いは？」コメントとdocstringについて解説します

f:id:kenken0326:20191115154936p:plain

こんにちはPyQサポートです。今回は、「コメント(#)とdocstring(""")の違い」を解説します。

質問
回答
まとめ

質問

このコードの中で """〜""" をメモのように使用していますが、 # の場合とは何が違うんでしょうか？

class RoomCounter:
    """ 部屋に入っている人数を管理するクラス
    エアシャワーの人数 (num_air) と部屋全体の人数 (num_room) を管理できる。

    部屋に入った人はまずエアシャワーに入ってから部屋に入るので、
    エアシャワーにいる人数は別途管理する。
    """
    def __init__(self):
        # _num_airの人数を適切に管理するため、別プログラムから直接属性を変更しない
        self._num_air = 0
        self._num_room = 0
        
    def room_in(self, num):
        """ 部屋とエアシャワーにnum人入る
        _num_roomには人数をそのまま追加し、_num_airには人数を設定する
        """
        self._num_air = num
        self._num_room += num
        
    def room_out(self):
        """工場から一人でる"""
        self._num_room -= 1
        
    def num_air(self):
        """エアシャワーの人数"""
        return self._num_air
    
    def num_room(self):
        """工場内の人数"""
        return self._num_room


rc = RoomCounter()
rc.room_in(3)
rc.room_out()
print(rc.num_air())
print(rc.num_room())

回答

`#` から始まる行はコメントです

# _num_airの人数を適切に管理するため、別プログラムから直接属性を変更しない

# から書き始める行はコメントです。公式ドキュメントに「コメントは構文上無視されます」と書かれている通り、コメントはプログラム上記述されていないものとして処理されます。

Pythonにおいてはコメントはなぜそうプログラムするのかという理由を書くことを意識すると良いでしょう。プログラムを後で読んだ人が「なぜこう書くのか？」と疑問を持つであろうところに説明を書きます（詳しくは後述します）。

`"""` で文字列を囲んだものの説明

関数やクラス、モジュールの最初の行に書かれた文字列をdocstring（Pythonファイルにつける説明文）と呼びます。次のように書くと関数のドキュメントとして扱われます。

def say_hello():
    """ この関数は hello を表示します
    """
    print('hello')

""" で文字列を囲んだものはPythonにおける「文字列」です。
これは以下のs と同じように、単なる文字列にすぎません。

s = """Hello
複数行の文字列"""

docstringとは何？

docstringはPythonでは関数、メソッド、クラス、モジュールの直下に書かれた文字列です。この文字列をPythonが「この文字列はドキュメント用の文字列だ！」と解釈してくれます。

たとえば、組み込みの help 関数を使うと docstring を表示してくれます。

>>> def foo():
...     """ fooの説明です """
...
>>> help(foo)
Help on function foo in module __main__:

foo()
    fooの説明です

コメントと明確に違い、関数などの説明のために書かれるドキュメントが docstring です。「この関数はこういうものだよ」「こういう使い方をするよ」という説明にはdocstringを使いましょう！

コメントに「何をしているか」をなるべく書かない

以下のように「何をしているか」を説明するコメントはなるべく書かないようにしましょう。理由は、プログラムを読めば理解できるので説明する意味がないからです。

# 属性 _num_root に num の値を加算する
self._num_room += num

プログラムが何をしているかが余程複雑な場合はコメントで説明すると良いでしょう。

# textが商品コードにマッチする場合
if re.search(r"[1-9]{1}[0-9]{32}", text):

けれどもこのような場合も、関数化することによって説明するのが理想です。ここで登場するのがdocstringです。処理をきれいに関数にまとめてdocstringを書くことで、プログラムの意図が明確になります。

PRODUCT_CODE_REGEX = re.compile(r"[1-9]{1}[0-9]{32}")

def validate_product_code(code: str) -> bool:
    """ 正しい商品コードの場合にTrueを返す関数
    商品コードの仕様はドキュメントを参照してください
    https://example.com/.../
    """
    return PRODUCT_CODE_REGEX.fullmatch(code)

...

if validate_product_code(text):
    ...