Python | 文法の基本：コメント記法

Python
スポンサーリンク

コメントとは

コメントは、コードの意味や意図、注意点を「未来の自分や他人」に伝えるための説明文です。Pythonインタプリタはコメントを完全に無視するので、動作や出力には影響しません。わかりやすいコメントは、理解の速度を上げ、バグの予防や保守のコストを下げます。特に「なぜこの実装なのか」「前提条件は何か」を書くと、ただの説明を超えて価値が高まります。

単一行コメントの基本

先頭に # を置く

Pythonの最も基本的なコメントは、行頭や行中で # を使う単一行コメントです。# 以降はその行の終わりまでがコメントとして無視されます。

# 合計を計算する（税抜）
total = 1200 + 800

price = 1000  # この価格は割引適用前
Python

「何をしているか」よりも「なぜそうしているか」を書くと役立ちます。

# APIの仕様上、タイムアウトを短く設定（3秒）しないと再試行が走らない
TIMEOUT_SEC = 3
Python

一時的な無効化（コメントアウト）

動作確認やデバッグのために、一部のコードを「一時的に無効化」する使い方です。削除せずに意図を残せます。

# print("冗長なログ")  # いまは静かにテストしたいので無効化
Python

複数行の説明をしたいとき

# を行ごとに使う

PythonにはC言語のようなブロックコメント構文（/* … */）はありません。複数行説明が必要なら、行ごとに # を付けて整えます。

# この関数はCSVを読み込み、
# - 空行をスキップ
# - ヘッダの有無を自動判定
# - 文字コードの推測に失敗したらUTF-8を既定値にする
def read_csv(path):
    ...
Python

文字列リテラルをコメント代わりに使わない

三重引用符の文字列（”””…”””）を「コメント代わり」に書くと、実際には文字列オブジェクトが生成されるので非推奨です。複数行の説明は素直に # を使いましょう。三重引用符は次の「docstring」でこそ本領を発揮します。

ドキュメンテーション文字列（docstring）

関数・クラス・モジュールの公式説明

docstringは、宣言の直後に書く三重引用符の文字列で、そのオブジェクトの「公式説明」として組み込まれます。ツールやIDEから参照され、help() にも表示されます。仕様や使用方法、引数・戻り値、例外、例を記載すると効果的です。

def calc_tax(amount, rate=0.1):
    """
    税込金額を計算して返す関数。

    引数:
      amount: 税抜金額（0以上）
      rate: 税率（0以上、既定は0.1）

    戻り値:
      税込金額（四捨五入）

    例外:
      ValueError: 負の値が渡された場合

    例:
      >>> calc_tax(1000)
      1100
      >>> calc_tax(1000, 0.08)
      1080
    """
    if amount < 0 or rate < 0:
        raise ValueError("負の値は不可")
    tax = round(amount * rate)
    return amount + tax
Python

help(calc_tax) を実行すると、docstringの内容が表示されます。テスト可能な例（doctest形式）を書くと、ドキュメントが動く仕様書になります。

クラス・モジュールにも書く

class User:
    """
    ユーザー情報を保持する簡易クラス。

    属性:
      name: 氏名
      age: 年齢（0以上の整数）
    """

    def __init__(self, name: str, age: int):
        self.name = name
        self.age = age
Python

モジュール全体の意図や前提は、ファイル先頭のdocstringにまとめると読み手が迷いません。

"""
レポート生成ツール（週次/月次対応）。

前提:
- 入力CSVはUTF-8
- 金額は税抜で記録

制限:
- 10万行を超えるとパフォーマンス低下
"""
Python

コメントを書くときの重要ポイント

「なぜ」を中心に書く

「何をしているか」はコードから読み取れます。コメントでしか伝えられない価値は「選択の理由・背景・制約」です。

# なぜ: サーバ側のバグで偶数ページだけ404になるため、奇数ページに合わせて再試行回数を増やす
RETRY_COUNT = 3
Python

前提・副作用・注意点を明示する

呼び出し側に影響する仕様は、コメントで早めに明示すると事故が減ります。

def normalize(items):
    # 副作用: 渡されたリストを破壊的にソートする（新しいリストは作らない）
    items.sort()
    return items
Python

TODOやFIXMEを活用する

「後でやる」「既知の欠陥」の印として、検索しやすい書式に統一します。

# TODO: localeごとの日付フォーマット対応
# FIXME: 0円の場合の丸め処理が不正確
Python

余計な説明は避ける

コードそのものをなぞるコメントは読み手の集中を削ります。命名と構造を改善し、コメントは最小限で最大の効果に。

# 悪い例：x に 10 を代入する
x = 10

# 良い例：意図を伝える
MAX_RETRY = 10  # APIベンダー推奨の上限
Python

実用的な例題

例題1：関数の仕様をdocstringで伝える

関数の使い方が一目でわかるように、入力・出力・例外・例を含めます。

def parse_price(text: str) -> int:
    """
    価格文字列（例: '1,280円'）を整数（1280）に変換する。

    引数:
      text: 価格を含む文字列。カンマ・単位は含まれていてもよい。

    戻り値:
      整数の価格（円）

    例外:
      ValueError: 数値が見つからない場合

    例:
      >>> parse_price("1,280円")
      1280
    """
    import re

    m = re.search(r"\d[\d,]*", text)
    if not m:
        raise ValueError("数値が見つかりません")
    return int(m.group().replace(",", ""))
Python

例題2：「なぜ」をコメントして将来の混乱を防ぐ

仕様の背景を書いておくと、後で別の人が安心して変更できます。

def round_tax(amount: float) -> int:
    # なぜ: 業務仕様で税額は四捨五入ではなく「切り捨て」。会計システムと一致させる必要がある。
    return int(amount)
Python

例題3：副作用の注意書きでバグ予防

引数が破壊的に変更されることを明示します。

def dedupe_in_place(items: list) -> None:
    # 前提: itemsはハッシュ可能な要素のみ
    # 副作用: ソートと重複削除により順序が変わる
    s = sorted(set(items))
    items[:] = s
Python

便利な周辺知識

エンコーディングとシェバン

ファイルの先頭に書くメタ情報は、コメント扱いでありながら動作に関与します。

#!/usr/bin/env python3         # 実行環境のPythonでスクリプトを起動（UNIX系）
# -*- coding: utf-8 -*-        # 文字コードの宣言（現代ではUTF-8が既定だが互換目的で使うことあり）
Python

型ヒントとコメントの使い分け

Pythonでは型は「型ヒント」で書くのが基本です。コメントは型そのものよりも、制約・例外・意図を補うために使い分けます。

from typing import Iterable

def total(xs: Iterable[int]) -> int:
    # 前提: xsは有限のイテラブル
    return sum(xs)
Python

まとめ

コメントは「読む人への手紙」です。コードからは読み取れない「なぜ」「前提」「副作用」「制約」を短く具体的に書き、複数行は # で整え、構造的な説明はdocstringに載せましょう。冗長な説明は避け、命名と設計で可読性を上げつつ、コメントは要点に集中させるのが最短ルートです。

スポンサーリンク
タイトルとURLをコピーしました