［解決！Python］Pythonでコメントを書くには：解決！Python

ブロックコメント、インラインコメント、docstringを使ったコメントやドキュメントの基本的な記述方法を紹介する。

[かわさきしんじ，Deep Insider編集部]

連載目次

# ブロックコメントの例
# This is a example of block comments.   Block comments consist of lines
# that start with # sign.  Note that after . sign, two white space chars
# follow it.

# インラインコメントの例
def do_nothing():
    pass  # This function doesn't do anything.  # ← インラインコメント

# docstring（ドキュメント文字列）の例
def swap(x, y):
    """swap x and y and return them"""  # ← 単一行のdocstring
    return y, x

def fizzbuzz(x):  # 複数行のdocstring
    """Inspect x about 'FizzBuzz' and return result.

    If x is a multiple of 15, return 'fizzbuzz',
    else if x is a multiple of 3, return 'fizz',
    else if x is a multiple of 5, return 'buzz',
    else return str(x).

    Argument:
    x -- integer

    Return:
    'fizz', 'buzz', 'fizzbuzz', or str(x).
    """
    if not isinstance(x, int):
        raise TypeError()

    if x % 15 == 0:
        return 'fizzbuzz'
    elif x % 3 == 0:
        return 'fizz'
    elif x % 5 == 0:
        return 'buzz'
    else:
        return str(x)

コメントの種類

　Pythonのコメントは「#」記号で始まり、行末で終了する。PEP 8では、コメントを次の2種類に分類している。

• ブロックコメント
• インラインコメント

　ブロックコメントとは、行が#記号で始まるコメントのことだ（ただし、行頭から#記号までの間に空白文字を含むこともある）。ブロックコメントの例を以下に示す。

# Block comment example.
# Block comments consist of one or more lines.

　インラインコメントとは、ある行にコードを書き、それに続けて書かれたコメントのこと。以下にインラインコメントの例を示す。

def do_nothing():
    pass  # This function doesn't do anything.  # ← インラインコメント

　この他にPythonではトリプルクオート文字列（「'''」または「"""」で囲まれたテキスト）をモジュール／関数／クラス／メソッドの定義の先頭に文字列リテラルとして記述することで、それらに関する説明を含んだコメントのように使用することがある（docstring、ドキュメント文字列）。以下にdocstringの例を示す。

def swap(x, y):
    """Swap x and y and return them"""  # ← 単一行のdocstring
    return y, x

ブロックコメント

　ブロックコメントはそれに続くコード全体に関する説明を記述するときに使用する。行頭に、またはブロックを示すインデントの後に「#」記号と半角空白文字を1つ続けて、その後にコメントの本文を記述する。以下に例を示す。

# Block comment on module top level.
# fizzbuzz function: resolves a fizzbuzz problem.

def fizzbuzz(x):
    if not isinstance(x, int):
        raise TypeError()

    # Block comment indented to function block.
    # If x is a multiple of 15, returns 'fizzbuzz',
    # else if x is a multiple of 3, returns 'fizz',
    # else if x is a multiple of 5, returns 'buzz',
    # else returns x.
    if x % 15 == 0:
        return 'fizzbuzz'
    elif x % 3 == 0:
        return 'fizz'
    elif x % 5 == 0:
        return 'buzz'
    else:
        return str(x)

　この例では、先頭の2行はその後に続くコードの説明を記述するブロックコメントとなっていて、fizzbuzz関数の概要を述べている。fizzbuzz関数内部のブロックコメントは関数の本体とインデントを合わせている（実行時にコメントは無視されるので、実際にはインデントを合わせる必要はないが、見通しのよさを考えるとコードブロックのインデントとブロックコメントのインデントは合わせておいた方がよいだろう）。

　上の例では、関数本体にあるブロックコメントの内容は「if文で行っている処理をそのまま書き下したもの」であり、これはコードを見れば自明なので実際にはこうしたコメントは不要だろう。上のコードで、どうしても書くとしたら「なぜx % 15 == 0が他の条件よりも先にあるのか」の方がまだましかもしれない（それすら不要だろう）。

インラインコメント

　インラインコメントには、それを記述した行に書かれているコードに関する説明を記述する。その際、コードの後には半角空白文字を最低でも2つ、その後に#記号と半角空白文字を1つ続けてから、コメントを記述する。

　ブロックコメントと同様に、コードが自明であるときに、それをそのまま書き下したコメントは不要だ。また、インラインコメントはうるさく感じるので、PEP 8ではなるべく使わないようにすることが推奨されている。

　以下は上のブロックコメントをif文の各節にインラインコメントとして記述したものだが、コードに続くコメントがうるさく感じるし、コードそのままの説明なので意味がない。

def fizzbuzz(x):
    if not isinstance(x, int):
        raise TypeError()

    if x % 15 == 0:  # if x is a multiple of 15, return 'fizzbuzz'
        return 'fizzbuzz'
    elif x % 3 == 0:  # if x is a multiple of 3, return 'fizz'
        return 'fizz'
    elif x % 5 == 0:  # else if x is a multiple of 5, return 'buzz'
        return 'buzz'
    else:  # else return 'fizzbuzz'
        return str(x)

　そうではなく、以下のように「15の倍数は3か5の倍数でもある」（から、最初に書いておく必要がある）といったコメントだけを記述した方がよいだろう。

def fizzbuzz(x):
    if not isinstance(x, int):
        raise TypeError()

    if x % 15 == 0:  # Multiple of 15 is also a multiple of 3 and 5.
        return 'fizzbuzz'
    elif x % 3 == 0:
        return 'fizz'
    elif x % 5 == 0:
        return 'buzz'
    else:
        return str(x)

docstring