［解決！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

　docstring（ドキュメント文字列）は、モジュール／関数／クラス／メソッドの定義の先頭に置かれたトリプルクオート文字列リテラルのことだ。PEP 257では一貫性を持たせるために「'''」ではなく「”””」を使うことが推奨されている。

　Pythonの処理系はこれらの文字列を認識して、プログラム実行時にdocstringをオブジェクトの__doc__属性の値としてくれる。そのため、「help(オブジェクト)」を実行したときに、そのオブジェクトのヘルプとしてdocstringが表示されるようになる。こうしたことから、docstringを記述することが推奨されている。

　docstringには「単一行のdocstring」と「複数行のdocstring」がある。単一行のdocstringは対象が「何をして、何を返すのか」を簡潔に記述するものだ。

def plus(a, b):
    """Add a and b and return result."""
    return a + b

　単一行のdocstringでは、文字列先頭の「"""」と末尾の「"""」は同じ行に書き、docstringの前後に空行は置かない。

　これに対して、複数行のdocstringでは単一行のdocstringと同様な概要を述べた後に、空行を挟んで、詳細な情報を記述する。関数のdocstringの例を以下に示す。

def fizzbuzz(x):
    """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)

　概要は上の例にあるようにdocstring先頭の「"""」に続けて書くか、その次の行に書く。その後に空行を入れて、関数の振る舞いやパラメーター、戻り値についての説明を記述する（fizzbuzz関数は例外を送出する可能性があるので、本来はそれらも記述すべきだ）。

　コメントとは異なり、docstringは文字列リテラルなので、インデントは記述位置のブロックに合っている必要があることには注意しよう。

注意点

　PEP 8では、コメントについて次のように定められている。

• #記号の後には半角空白文字を1つ置く
• コメントに複数の文が含まれている場合、文末のピリオドと次の文の間には半角空白文字を2つ含める
• そのコードを自分が使っている言語の話者以外が絶対に読まないことが分かっている場合を除いて、コメントは英語で書くことが推奨される（そのため、筆者の下手くそな英語がコメントの例となっている）

　実際にはPEP 8だけがコーディングスタイルガイドではないし、docstringの書き方にもさまざまな流派があるので、どのような書き方が適切かは読者の環境に合わせて変わるはずだ。docstringの書き方については機会があれば別稿で取り扱うことにする。

「解決！Python」