Pythonではコメントを使うことで、コードの意図や注意点を自分や他人に伝えやすくなります。
特に初心者のうちは、後から見返しても理解できるよう丁寧にメモを残すことが重要です。
本記事では、Pythonのコメントの基本から複数行コメント、docstringの使い方、そして実務で役立つベストプラクティスまでを、実行例とともに段階的に解説します。
Pythonのコメントの基本と書き方
コメントとは何か
コメントの目的
コードは未来の自分やチームメンバーへのコミュニケーションの手段でもあります。
コメントは「なぜその実装になっているのか」という意図や背景を補足するために書きます。
アルゴリズムの概要、仕様の根拠、注意事項などはコメントが適しています。
Pythonにおける基本ルール
Pythonでは行頭または行中で#から行末までがコメントになります。
インタプリタはコメントを無視するため、実行速度に影響しません。
まずは#を使うのが最も基本的で確実な方法です。
下表に各手段の位置づけを整理します。
| 手段 | 記法 | 適用対象 | 実行時の扱い | 主な用途 |
|---|---|---|---|---|
| 1行コメント | # これはコメント | 任意の行 | 無視される | 意図や補足 |
| インラインコメント | コード # 補足 | 行末 | 無視される | 局所説明 |
複数行(連続#) | # ...を連続 | まとまった説明 | 無視される | 仕様・注意点 |
| 複数行文字列 | """...""" | 文の位置に依存 | 先頭ならdocstring、他は文字列リテラル | ドキュメント |
| docstring | """説明...""" | モジュール/クラス/関数の先頭 | help()等に表示 | API仕様 |
1行コメントの書き方と例
基本形
1行コメントは#から行末までが対象です。
#の直後に半角スペースを入れると読みやすくなります(PEP 8)。
# あいさつを出力するプログラム
message = "Hello, Python!"
print(message) # 画面に文字を表示Hello, Python!実行例のポイント
出力自体にはコメントは影響しません。
上では# 画面に文字を表示がインラインコメントとして補足を担っています。
インラインコメントの使い方と例
使いどころ
行の末尾に短い補足を書くと、式の意味を瞬時に理解できます。
「何をしているか」よりも「なぜそうするか」を書くと価値が上がります。
# 支払い金額の計算例
price = 1200 # 本体価格(円)
tax_rate = 0.1 # 消費税率(10%)
total = int(price * (1 + tax_rate)) # 仕様: 1円未満は切り捨て
print(total)1320一時的にコードを無効化するコメントアウト
方法と注意
デバッグ中に一部の行を無効化したいときは#を先頭に付けます。
コメントアウトした行を放置しないのが良い習慣です。
原因が解決したら削除しましょう。
# 検証のため一部のprintを一時停止
print("start")
# print("debug: 詳細ログ") # 一時的に無効化
print("end")start
end複数行コメントの書き方と注意点
# を使った複数行コメントの例
実例と整形
Pythonには専用の「複数行コメント構文」はありません。
複数行の#コメントを連続して書くのが標準的です。
# 処理の前提:
# - APIのタイムアウトは厳格である(3秒)
# - リトライは最大2回まで
# - レート制限超過時はバックオフを行う
timeout_sec = 3
retries = 2
print(timeout_sec + retries)5整形として区切り線を使うとブロックが視認しやすくなります。
# ===== 入力検証方針 =====
# 1) フィールド必須チェック
# 2) 形式チェック(メール・電話)
# 3) ビジネスルール
# =======================エディタのブロックコメント機能の使い方(VS Code / PyCharmの例)
多くのエディタは複数行を選択して#の付与・除去を一括で行えます。
たとえば以下が代表例です。
- VS Code: Windows/Linuxは
Ctrl + /、macOSはCmd + /でトグル。ブロック選択で複数行に適用できます。 - PyCharm: Windows/Linuxは
Ctrl + /、macOSはCmd + /。ドキュメンテーション用の/**等はPythonでは使われません。
エディタの機能を使うと差分が綺麗になり、コメントの付け外しが安全です。
複数行文字列はコメントではない
複数行文字列""" ... """はコメントではありません。
式として評価される文字列リテラルです。
モジュール・クラス・関数の「最初の文」に置いた場合はdocstringとして使われますが、その他の位置では実行結果に使われない文字列が残るだけで、バイトコードやメモリの無駄になります。
複数行文字列を使ったNG例と注意点
NGコード例
次のgは関数内の2行目に文字列リテラルがあり、docstringにならず捨てられます。
def g():
x = 1
"""
これはコメントのつもりで書かれたNG例。
docstringにはならず、無意味なリテラルになります。
"""
return x
print(g())
print(g.__doc__) # docstringが付与されていないことを確認1
None例外: docstringになる位置
先頭に置けばdocstringとして正しく扱われます。
コメントの代用ではなく、公開インターフェイスの説明として使いましょう。
def ok():
"""1を返す単純な関数。テスト用。"""
return 1
print(ok())
print(ok.__doc__)1
1を返す単純な関数。テスト用。docstringの書き方と使い分け
関数のdocstringの書き方と例
Googleスタイル例
docstringは外部に向けたAPIの説明です。
引数や戻り値、例外、使用例を簡潔に書きます。
def add(a: int, b: int) -> int:
"""2つの整数を加算して返します。
Args:
a: 左の整数。
b: 右の整数。
Returns:
合計値。
"""
return a + b
print(add(2, 3))5簡潔版例
短い関数は1行でも十分です。
def is_even(x: int) -> bool:
"""xが偶数ならTrueを返します。"""
return x % 2 == 0クラスとモジュールのdocstring
クラスdocstring
クラスの目的や主な属性を記述します。
import time
class Timer:
"""経過時間を計測する簡易タイマー。
Attributes:
start: 開始時刻(秒)。
"""
def __init__(self) -> None:
"""タイマーを初期化します。"""
self.start = time.perf_counter()
def elapsed(self) -> float:
"""開始からの経過秒数を返します。"""
return time.perf_counter() - self.start
t = Timer()
time.sleep(0.05) # 50ms待機
print(round(t.elapsed(), 3))0.05モジュールdocstring
ファイル先頭の"""..."""はモジュールdocstringです。
用途や主要関数を記述します。
"""文字列ユーティリティ(トリミングや大文字化を提供)。"""
def shout(s: str) -> str:
"""末尾の空白を削除し、大文字に変換して!を付けます。"""
return s.rstrip().upper() + "!"コメントとの違いと使い分け
- コメントは実装の背景や注意点(Why/Why not)をコードの近くに書きます。
- docstringは関数やクラスの使い方(What/How to use)を外部向けに書きます。
- 内部実装の詳細はコメント、公開APIの説明はdocstringと覚えると整理しやすいです。
helpと__doc__でdocstringを確認する
help()や__doc__属性で確認できます。
def mul(a: int, b: int) -> int:
"""2つの整数を乗算して返します。
Args:
a: 被乗数。
b: 乗数。
"""
return a * b
print(mul.__doc__) # 文字列としてdocstringを取得
help(mul) # 整形されたヘルプを表示(対話型で便利)2つの整数を乗算して返します。
Help on function mul in module __main__:
mul(a: int, b: int) -> int
2つの整数を乗算して返します。
Args:
a: 被乗数。
b: 乗数。コメントのベストプラクティス
PEP 8に沿ったコメントスタイル
重要ポイント
PEP 8はPythonの公式スタイルガイドです。
コメント関連の要点は次の通りです。
「読みやすく、正確で、最新」を常に満たしましょう。
#の後に半角スペースを1つ入れる(# 説明)。- ブロックコメントは段落として書き、各行を
#で始める。 - 行の長さはコード79桁、コメントやdocstringは72桁を目安に折り返す。
- コードと矛盾しない最新の内容に保つ。曖昧な表現は避ける。
よい例/悪い例
# 悪い例: スペースなし、情報がない
x = 10 #増やす
# 良い例: スペースあり、意図が伝わる
x = 10 # 仕様: 初期在庫(個)。外部設定がない場合のデフォルトよくあるミスとアンチパターン
具体例
- コードの「翻訳」だけを書く:
# xに1を足すのような冗長な説明は不要です。 - 将来にわたって嘘になる: 仕様変更後に放置されたコメントは害になります。
- インラインコメントが長すぎる: 行を圧迫する場合は直前にブロックコメントで説明しましょう。
- 複数行文字列でコメントの代用: 先述の通りNGです。
TODOやFIXMEの書き方
形式と運用
未完了の作業や既知の問題は、検索しやすい形式で残します。
責任者や日付を付けると管理しやすくなります。
# TODO(yamada, 2025-09-10): 429時の指数バックオフを実装する
# FIXME: タイムアウトが短すぎる可能性がある。設定値で上書きできるようにするツール(例: ruffやflake8-todos)で検出・可視化すると効果的です。
日本語コメントのコツ
書き方のヒント
日本語で書く場合も、一文一義で簡潔に、主語や対象を明確にしましょう。
専門用語は英語表記を併記すると検索しやすくなります(例: バックオフ(backoff))。
チームで用語集を共有するとぶれが減ります。
コメントよりコードで表現する
リファクタ例
読みやすいコードはコメントを減らせます。
名前付けと小さな関数化が有効です。
# 悪い例: コメントで目的を説明
# リストから偶数のみを抽出する
result = []
for x in [1, 2, 3, 4, 5, 6]:
if x % 2 == 0:
result.append(x)
print(result)[2, 4, 6]# 良い例: コード自体が語る
from typing import Iterable, List
def is_even(x: int) -> bool:
"""偶数ならTrue。"""
return x % 2 == 0
def filter_even(xs: Iterable[int]) -> list[int]:
"""偶数だけを抽出して返します。"""
return [x for x in xs if is_even(x)]
print(filter_even([1, 2, 3, 4, 5, 6]))[2, 4, 6]型ヒントとコメントの使い分け
型ヒントの例
型を説明するためのコメントは、型ヒント(PEP 484)を使うと機械チェックでき、自己文書化にもなります。
from typing import Iterable
def mean(xs: Iterable[float]) -> float:
"""数値の平均値を返します。空の場合はValueError。"""
data = list(xs)
if not data:
raise ValueError("empty")
return sum(data) / len(data)古い型コメントとの違い
旧来の# type:コメントは新規コードでは推奨されません。
可能なら注釈を使いましょう。
# 旧: nums = [] # type: List[int]
# 新:
nums: list[int] = []型は型ヒント、運用や仕様の背景はコメントと切り分けるのがコツです。
まとめ
コメントはPythonコードの品質を高める重要な要素です。
基本は#で1行ずつ書き、複数行は#を連ねて表現します。
複数行文字列"""..."""はコメントの代用にせず、モジュール/クラス/関数の先頭でdocstringとして活用しましょう。
PEP 8に沿って簡潔かつ正確に、最新の情報を保つことで、将来の自分やチームに価値あるドキュメントになります。
最後に、コメントで補う前にコードで表現できないかを常に検討し、必要なコメントは「なぜ」を中心に書くことを心がけてください。
