コメントの活用

コードを後から読み返したとき、「これ、何のために書いたんだっけ？」と迷ったことはありませんか？

そんなときに役立つのがコメントです。Pythonのコメントを上手に使うと、コードの可読性と保守性がぐっと上がります。

ここでは、IT初心者の方でもわかりやすいように、「Pythonのコメントの書き方」「docstring（ドキュメンテーション文字列）の使い方」「行内コメントやブロックコメントの使い分け」を、サンプルコードとともに丁寧に解説します。

コメントの種類を正しく使い分けよう

まずは全体像をつかむために、Pythonでよく使われるコメントの種類を整理します。どれをいつ使うのかがわかると、読みやすいコードに一歩近づけます。

• 【行内コメント（inline comment）】 コードの行の末尾に短く補足を書く方法です。計算式の意図など、その行の理解を助けるときに使います。
• 【ブロックコメント（block comment）】 数行にわたって、まとまりのある処理の概要や前提条件、注意点を説明します。複数行の先頭に#を付けて書くのが一般的です（未使用の三重引用符 """ を“コメント代わり”に使うのは推奨されません）。
• 【ドキュメンテーション文字列（docstring）】 関数・クラス・モジュールのすぐ下に書く特別な文字列で、使い方、引数、戻り値、例外などを説明します。エディタのホバーやヘルプ（help関数）から参照できるため、再利用性を高めます。

サンプルコードで「良いコメント」を体験しよう

ここでは、円の面積を求めるシンプルなプログラムに、初心者にも役立つコメントを添えてみます。

読みながら「なぜこのコメントが必要なのか？」を意識してみてください。

from math import pi  # 標準ライブラリの高精度な円周率を利用

def calculate_area_of_circle(radius: float) -> float:
    """円の面積を返す。

    Args:
        radius: 円の半径（0以上の数）

    Returns:
        円の面積（πr^2）

    Raises:
        ValueError: 半径が負の値のとき
    """
    # 仕様として半径は負であってはならないため、防御的にチェックする
    if radius < 0:
        raise ValueError("半径は0以上にしてください。")

    area = pi * (radius ** 2)  # 面積 = πr^2（式の意図を短く明示）
    return area

radius = 3.5  # 半径のサンプル値。必要に応じて変更可能

# --- 計算と出力 ---
area = calculate_area_of_circle(radius) 
print(f"半径 {radius} の円の面積は {area:.2f} です。")

最初に目に入る行内コメント「標準ライブラリの高精度な円周率を利用」は、なぜmath.piを使うのかという「意図」を短く伝えています。 値を直書きするよりも、標準ライブラリの定数を採用する理由が一言あるだけで、読む人は納得しやすくなります。

関数の直下にある三重引用符の文字列はdocstring（ドキュメンテーション文字列）で、引数、戻り値、起こりうる例外を明示しています。docstringはエディタの補完やhelp関数で参照でき、他の人が関数を再利用するときの「取扱説明書」になります。コメントよりも一段深く「どう使うか」を説明できる点が強力です。

半径が負数のときにValueErrorを投げる前のコメントは、「何をしているか」ではなく「なぜそうするか」を説明しています。この“なぜ”の説明は、将来の自分や他人が仕様を読み解くときの大きな助けになります。単なる「入力チェック」ではなく、「仕様として負は不可だから」という背景を短く添えています。

また、areaの計算式の末尾にある行内コメント「面積 = πr^2」は、式の由来を端的に伝えています。コードを初めて読む人でも、数学的な意味をすぐに結びつけられます。

よくある失敗と改善例を見てみよう

ここからは、ありがちな「悪いコメント」と、それを「良いコメント」に直す例を比べてみます。 あなたの普段の書き方と見比べて、気づきを持ち帰ってください。

悪い例（何をしているかだけを重複して説明）

area = pi * (radius ** 2)  # 面積を計算する

良い例（なぜ・前提・根拠を短く伝える）

area = pi * (radius ** 2)  # 面積 = πr^2（中学数学の公式に基づく）

悪い例（コードの変化に追随しづらい曖昧なコメント）

# TODO: いつか直す
validate(user)

良い例（行動と条件が明確）

# TODO(2025-01): 外部ID導入後にemail重複チェックを削除する
validate(user)

悪い例（コメントアウトされた古いコードの放置）

# old_api_call(user)  # もう使っていない
new_api_call(user)

良い例（履歴はGitに任せ、コードは最新だけを残す）

new_api_call(user)  # 新APIでレート制限を回避

コメントのベストプラクティス

ここからは実務でも役立つ「Python コメントの書き方」のコツをまとめます。読む人にとって価値がある情報を、過不足なく届ける意識が大切です。

• 【「なにを」より「なぜ」を書く】 コードを見れば「なにをしているか」はたいてい分かります。設計の意図、採用したアルゴリズムの理由、制約、ドメイン知識など、コードから読み取りにくい背景を補いましょう。
• 【docstring は「使い方の説明書」】 関数・クラスの目的、引数、戻り値、例外、前提条件、簡単な使用例を記載します。エディタやhelp()から確認でき、チームの生産性が上がります。
• 【コメントは最新に保つ】 コードを変更したら関連コメントも必ず更新します。古いコメントは誤解を生み、バグの温床になります。
• 【過剰なコメントは避ける】 当然のことやコードと完全に重複する説明はノイズになります。命名（意味のある変数名・関数名）と構造化（関数分割）で、コメントの量そのものを減らすのが理想です。
• 【フォーマットと用語を統一する】 プロジェクト内でdocstringのスタイル（Google/NumPy/ReSTなど）や注記（TODO/FIXME/NOTE）を統一すると、読みやすさが一段と上がります。
• 【コメントで一時的な仕様や外部要因を明記する】「一時対応」「特定バージョンのバグ回避」「法的・業務上の制約」など、コードだけでは伝わらない事情を書き添えます。

これらを意識して、良いコメントを書いてみましょう！

まとめ

Pythonのコメントは、単なるメモではなく「読みやすいコード」を支える重要なドキュメントです。行内コメントで意図を補い、ブロックコメントで流れを整理し、docstringで使い方を明確にする。こうした積み重ねが、保守性やチームの生産性を大きく引き上げます。

今日から、ただ動くコードから「未来の自分が読みたくなるコード」へ。あなたの一行のコメントが、プロダクトの品質を向上させます。