Python 逆引き集 | Python基礎・実行環境：複数行コメントを書く

Python Python
スポンサーリンク
スポンサーリンク

Python基礎・実行環境と「複数行コメント」の位置づけ

Pythonを学び始めると、「コメントは # で書く」というところまではすぐに覚えられますが、「複数行コメントはどう書くのか？」で戸惑う方がとても多いです。 しかもPythonには、CやJavaのような /* ... */ 専用構文がありません。ここを正しく理解しておくと、読みやすくて安全なコードを書きやすくなります。

Pythonにおける複数行コメントの考え方

専用構文は「存在しない」という事実

Pythonには「複数行コメント専用の構文」はありません。 言語仕様としてあるのは、行頭から行末までをコメントにする # だけです。

ではどうするかというと、次の2パターンが実務で使われています。

  • # を複数行にわたって並べる（ブロックコメント）
  • トリプルクォート（""" や '''）で文字列を囲み、実質的なコメントとして使う

それぞれのメリット・注意点を、例題と一緒に見ていきます。

# を使った複数行コメント（いちばん「Python的」な方法）

基本形

複数行コメントのいちばん素直な書き方は、各行の先頭に # を付ける方法です。

# この関数は売上データを集計します。
# 仕様：
# - 日次データを月次にまとめる
# - 欠損値は0として扱う
def aggregate_sales(records):
    ...
Python

この書き方は、Pythonのスタイルガイドや多くの解説記事でも「もっともPython的で推奨される方法」とされています。

ブロックコメントとしてそろえる

読みやすくするために、インデントをコードとそろえるのがポイントです。

def process():
    # 入力データの検証を行います。
    # - 必須項目が埋まっているか
    # - 型が正しいか
    # - 範囲外の値がないか
    validate()
Python
  • コメントのインデントを処理の位置に合わせることで、「どのブロックの説明なのか」が一目でわかります。

エディタのショートカットを活用する

VS Code や多くのエディタでは、範囲選択して Ctrl + /（Macは Cmd + /） を押すと、選択行すべてに # を付けたり外したりできます。

これを使うと、

  • 既存コードを一時的に「コメントアウト」したいとき
  • まとまった説明をブロックコメントとして挿入したいとき

に、複数行コメントを一瞬で作れるようになります。

トリプルクォートを使った複数行コメント

仕組みの本質：あくまで「文字列リテラル」

Pythonでは、""" ... """ や ''' ... ''' で囲んだ部分は複数行の文字列リテラルです。 「コメント専用構文」ではありません。

"""
このブロックは複数行コメントのように見えますが、
実際にはただの文字列リテラルです。
インタープリタは文字列オブジェクトを作成し、
どこにも使われなければ捨てます。
"""
print("処理を開始します")
Python
  • どこにも代入されていないため、実行時には「作られて捨てられるだけ」の文字列になります。

docstring との違い

モジュール・クラス・関数の先頭に置かれたトリプルクォート文字列は、特別扱いされて「docstring」として保存されます。

def add(a, b):
    """
    2つの数値を受け取り、その合計を返します。
    Parameters:
        a (int or float): 1つ目の値
        b (int or float): 2つ目の値
    Returns:
        int or float: 合計値
    """
    return a + b
Python
  • この文字列は add.__doc__ として参照でき、IDEのヘルプや自動ドキュメント生成に使われます。

重要なポイントは、

  • 「docstring」はAPIの説明用
  • 「コメント」はロジックの意図や注意点の説明用

と役割が違うことです。 ロジックの途中にトリプルクォートを置いて「なんとなくコメントっぽく使う」のは、スタイル的にも推奨されません。

実務での使い分けとテンプレート

基本方針

  1. 通常の説明・注意書き → # を複数行に並べる
  2. 関数・クラス・モジュールの仕様説明 → docstring（トリプルクォート）

この2段構えで考えると、迷いがほとんどなくなります。

ブロックコメントのテンプレート

# 【目的】売上データを月次単位に集計する。
# 【仕様】欠損値は0扱い。異常値はログに記録して除外する。
# 【注意】API仕様変更時はこのロジックを必ず見直すこと。
def aggregate_sales(records):
    ...
Python
  • 「目的」「仕様」「注意」の3つを意識すると、コメントが具体的になります。

docstring のテンプレート

def send_email(to, subject, body):
    """
    メールを送信します。

    Parameters:
        to (str): 宛先メールアドレス。
        subject (str): 件名。
        body (str): 本文。

    Returns:
        bool: 送信に成功した場合は True、失敗した場合は False。
    """
    ...
Python
  • 関数の「外から見える仕様」をまとめる場所としてdocstringを使います。

練習：複数行コメントを書いてみる

練習コード

次のコードに、複数行コメントを追加してみるイメージで考えてください。

def calculate_final_price(price, discount_rate, tax_rate):
    final = price * (1 - discount_rate)
    final = final * (1 + tax_rate)
    return final
Python

例としてのコメント付きバージョン

# 【目的】割引と税を適用した最終価格を計算します。
# 【仕様】
# - discount_rate は 0.0〜1.0 の範囲（例: 0.2 は 20% 割引）。
# - tax_rate は 0.0〜1.0 の範囲（例: 0.1 は 10% の税）。
# 【注意】負の値が渡された場合は別途バリデーションで弾くこと。
def calculate_final_price(price, discount_rate, tax_rate):
    final = price * (1 - discount_rate)
    final = final * (1 + tax_rate)
    return final
Python

このように、複数行コメントは「段落として説明を書く場所」だと考えると、自然に使えるようになります。

まとめ

  • Pythonには、CやJavaのような専用の複数行コメント構文はありません。
  • 実務では、# を複数行に並べるブロックコメントがもっとも推奨される方法です。
  • トリプルクォートは本質的には文字列リテラルであり、docstringとして使うのが正しい役割です。
  • 「ロジックの説明は #」「APIの仕様説明は docstring」という使い分けを意識すると、読みやすくて保守しやすいコードになります。

複数行コメントは、コードの「背景」「意図」「注意点」をまとめて伝えるための強力な道具です。 初心者のうちから、意味のある複数行コメントを書く習慣を身につけておくと、チーム開発でも信頼されるコードを書けるようになっていきます。

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