Python / 構文 / コメント

Pythonのコメントは文字列の外側の#からその行の終わりまで続きます。複数行なら各行に#を付け、三重引用符はコメント専用の構文ではなく文字列リテラルを作ります。関数などの先頭に置く文書文字列のdocstringも一般コメントとは区別します。

1行コメントと文字列内の#

コメントは意図や条件を説明し、通常の内容はPythonの構文解析で無視されます。行全体にもコードの後にも書けます。正確な範囲は公式のコメント規則で確認できます。

例はPython 3だけで動きます。全体をUTF-8のcomments_example.pyに保存し、python comments_example.py、環境によってはpython3で実行します。後の例も内容を置き換えて独立して実行できます。

# Calculate the total before discounts.
price = 100
quantity = 2  # Number of items
print(price * quantity)

期待される出力：

200

引用符内の#は文字列の一部です。ハッシュを含む文やURLのフラグメントがコメントとして切り捨てられるわけではありません。

print("# This is part of a string")
print("https://example.com/page#section")

# This is part of a string
https://example.com/page#section

長い説明には各行に#を付ける

PythonにはCの/* ... */のような独立したブロックコメント構文はありません。各行をコメントにし、説明対象のコードとインデントを合わせると関係がわかりやすくなります。

# The sample uses a fixed discount rate.
# Production rules may depend on the customer.
base_price = 100
discount_rate = 0.1
print(base_price * (1 - discount_rate))

90.0

一時的にコードを止めるなら各行をコメント化し、再開するときに解除します。エディターの複数行コメント操作も通常これを行います。古い実装をコメントで蓄積するより、バージョン管理の履歴に残すと現在のコードが読みやすくなります。

三重引用符とdocstringは文字列

三重の一重引用符・二重引用符は複数行を含められる文字列リテラルです。モジュール・クラス・関数の最初の文に置いた文字列はdocstringになり、__doc__やヘルプで利用されます。位置と目的はdocstringの公式説明を参照します。

def greet(name):
    """Return a greeting for name."""
    return f"Hello, {name}"

print(greet("Ada"))
print(greet.__doc__)

Hello, Ada
Return a greeting for name.

これは関数を文書化するアクセス可能な値で、通常の説明コメントとは異なります。同じ引用形式は実データの保存にも使います。

notes = """first line
second line"""
print(notes.splitlines())

['first line', 'second line']

任意のコードを三重引用符で囲んでも本当のコメントにはなりません。内部の同じ引用符で構文が壊れたり、位置によってdocstringになったりします。コードの無効化には#を使います。

コメントだけのブロックには文が必要

defやifなどのブロックには実際の文が必要です。コメントは文として数えないので、それだけ残すとIndentationErrorになり得ます。何もしない置き場にはpass文を使います。

source = "def todo():\n    # Implement later\n"
try:
    compile(source, "example", "exec")
except IndentationError:
    print("IndentationError")

def todo():
    # Implement later
    pass

print(todo())

IndentationError
None

最初は不正コードを文字列としてコンパイルし、例全体が止まらないよう例外を捕捉しています。後の関数はpassがあるので正しく定義でき、明示的なreturnがないため結果はNoneです。

役立つ説明と特別な指示

PEPはPython Enhancement Proposalの略です。PEP 8のコメント指針はコードと矛盾する説明に注意を促しています。明白な処理の繰り返しより、選択理由、外部制約や重要条件を説明し、変更時に更新します。通常の行末コメントは#の前に2個以上、後に1個の空白を置く形が推奨されます。

一部のコメントはツールやソース処理で意味を持ちます。1行目・2行目の正しいエンコーディング宣言は読み方に影響し、Python 3の既定はUTF-8です。リンターや型チェッカーの指示は通常の説明と区別し、原因を見ずに警告をまとめて隠さないようにします。