[解決!Python]Pythonでコメントを書くには解決!Python

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

» 2021年10月26日 05時00分 公開
[かわさきしんじDeep Insider編集部]

この記事は会員限定です。会員登録(無料)すると全てご覧いただけます。

「解決!Python」のインデックス

連載目次

# ブロックコメントの例
# 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」のインデックス

解決!Python

鬯ゥ謳セ�ス�オ�ス�ス�ス�コ鬯ョ�ヲ�ス�ョ髯キ�サ�ス�サ�ス�ス�ス�ソ�ス�ス�ス�ス鬯ッ�ッ�ス�ィ�ス�ス�ス�セ�ス�ス�ス�ス�ス�ス�ス�」鬯ッ�ョ�ス�エ髣費ソス�ス�・�ス�ス�ス�ウ�ス�ス�ス�ィ�ス�ス�ス�ス髯懶ス」�ス�、�ス�ス�ス�ク�ス�ス�ス�イ鬯ゥ蠅捺��ス�ソ�ス�ス�ス縺、ツ€�ス�ス�ス�ス�ス�ス�ス�」鬯ッ�ョ�ス�エ鬯ゥ蟶壽桶�ス�ュ鬮ョ�」�ス�ソ�ス�ス�ス�ス�ス�ィ鬮ッ蛹コ�サ繧托スス�ソ�ス�ス�ス�ス�ス�ス�ス�ス�ス�コ鬮」蛹�スス�オ髫エ謫セ�ス�エ�ス�ス隶難ス」�守「托スュ雜」�ス�「�ス�ス�ス�ス�ス�ス�ス�ゥ鬯ゥ蟷「�ス�「髫エ雜」�ス�「�ス�ス�ス�ス�ス�ス�ス�シ鬯ゥ蟷「�ス�「髫エ荳サ�ス隶捺サゑスソ�ス邵コ�、�つ€鬯ッ�ョ�ス�ヲ�ス�ス�ス�ェ鬩包スカ闔ィ�ス�ス�ヲ�ス�エ�ス縺、ツ€髯キ闌ィ�ス�キ�ス�ス�ス�ス�ス�ス�ス�サ鬯ッ�ッ�ス�ェ�ス�ス�ス�ュ�ス�ス�ス�ス�ス�ス�ス�イ鬯ゥ謳セ�ス�オ�ス�ス�ス�コ鬮ッ�キ�ス�キ�ス�ス�ス�カ�ス�ス�ス�ス�ス�ス�ス�ス New

Copyright© Digital Advantage Corp. All Rights Reserved.

スポンサーからのお知らせPR

Deep Insider 鬯ョ�ォ�ス�ェ髯区サゑスソ�ス�ス�ス�ス�コ髣包スオ隴∵コキ�ク�キ�ス�ケ隴趣ス「�ス�ス�ス�ウ鬩幢ス「�ス�ァ�ス�ス�ス�ュ鬩幢ス「隴趣ス「�ス�ス�ス�ウ鬩幢ス「�ス�ァ�ス�ス�ス�ー

鬮ォ�エ陝キ�「�ス�ス�ス�ャ鬮ォ�エ鬲�シ夲スス�ス�ス�・鬮ォ�エ陝カ�キ�ス�」�ス�ッ髣厄スォ�ス�」

注目のテーマ

4AI by @IT - AIを作り、動かし、守り、生かす
Microsoft & Windows最前線2025
AI for エンジニアリング
ローコード/ノーコード セントラル by @IT - ITエンジニアがビジネスの中心で活躍する組織へ
Cloud Native Central by @IT - スケーラブルな能力を組織に
システム開発ノウハウ 【発注ナビ】PR
あなたにおすすめの記事PR

RSSについて

アイティメディアIDについて

メールマガジン登録

@ITのメールマガジンは、 もちろん、すべて無料です。ぜひメールマガジンをご購読ください。