未来の自分や仲間のための道標。Pythonにおける「コメント」の書き方と活用の極意

【Yuki】 こんばんは、Hiroki君。今日も熱心にプログラミングの学習を進めているんですね。

静かな夜は、コードと向き合うのにとても良い時間だと思います……。わたしも、周りが静まり返った夜にキーボードを叩くのが好きなんです。

今日は、Pythonにおける「コメント」について、一緒に学んでいきましょう。プログラムを書く上で、コメントは単なる「メモ書き」以上の、とても大切な役割を持っているんですよ。

【Hiroki】 Yukiさん、こんばんは！夜の方が集中できるっていうの、なんだか分かります。

「コメント」ですね。以前少し触った時に、# を使って何かを書いた記憶がありますが……。プログラムの動作には直接関係ないんですよね？それなのに、そんなに大切なんですか？

【Yuki】 はい、その通りです。コメントに書かれた内容は、Pythonの実行環境（インタプリタ）からは完全に無視されます。

でも、プログラムは「動けばいい」というものではありません。後から自分で読み返したときや、他の誰かがそのコードを見たときに、「ここで何をしているのか」「なぜこう書いたのか」が伝わらないと、迷子になってしまうかもしれません……。

誰かの役に立つために作られた小さなツールが、時を経て誰かの手助けになる……。コメントは、そんな時にコードの意図を伝えるための「優しい道標」のようなものだと、わたしは思っています。

【Hiroki】 「優しい道標」……。確かに、数日前に書いた自分のコードの意味を忘れて困ったことがありました。

具体的に、Pythonではどうやってコメントを書けばいいのか、詳しく教えてください！

コメントの基本：1行コメント（#）の使い方

【Yuki】 まずは一番基本的な、1行コメントから説明しますね。

Pythonでは、#（シャープ）という記号を使います。この記号の後に続く文字は、その行の終わりまで全てコメントとして扱われます。

# これはコメントです。プログラムの実行には影響しません。
print("Hello, World!")  # コードの横に書くこともできます（インラインコメント）

【Hiroki】 あ、これですね！コードの横にも書けるのは便利そうです。でも、どんな時に使うのが良いんでしょうか？

【Yuki】 そうですね……。例えば、複雑な数式や、一見して意図が分かりにくい処理がある時に添えてあげると親切だと思います。

# 円の面積を計算する（半径 * 半径 * 円周率）
area = radius ** 2 * 3.1415926535

ただし、コードを見ればすぐに分かることをわざわざ書く必要はありません。

print("Hello") # Helloと表示する というようなコメントは、かえってコードを読みづらくしてしまう「ノイズ」になってしまうかもしれないので、注意してくださいね。

【Hiroki】 なるほど、「何をしているか」よりも「なぜそうしているか」や「何を意味しているか」を書くのがコツ、ということですね。

複数行のコメントと文字列を利用したテクニック

【Yuki】 Hiroki君、察しが良いですね。その通りだと思います。

次に、数行にわたって詳しく説明を書きたい場合についてお話しします。

実は、Pythonには厳密な意味での「複数行コメント専用の構文」はありません。一般的には、各行の先頭に # を置く方法が推奨されています。

# この関数は、ユーザーの入力した値をチェックし、
# 適切な形式に変換してからデータベースに保存します。
# 不正な入力があった場合は、ValueErrorを返します。
def process_user_data(data):
    pass

【Hiroki】 えっ、そうなんですか？他の言語だと /* ... */ みたいに囲む記号があるって聞いたことがありますが、Pythonは全部 # を書くのが基本なんですね。

【Yuki】 はい、Pythonのスタイルガイドである PEP 8 でも、ブロックコメントには # を使うことが推奨されています。

ただ、プログラミングの世界では、「トリプルクォート（""" または '''）」を使った複数行の文字列を、コメントのように扱う習慣もあります。

"""
ここもコメントのように
扱うことができます。
厳密には「文字列」ですが、どこにも代入しなければ
実行時には無視されます。
"""
print("文字列によるコメントの例です")

【Hiroki】 あ、これを見たことがあります！これなら長い文章も書きやすそうですね。

【Yuki】 ええ、そうですね。ただ、これには「docstring（ドキュメンテーション文字列）」という特別な役割があるんです。

docstring：関数やクラスの説明書を作る

【Yuki】 「docstring」は、関数やクラスの定義の直後に記述する、特別な文字列のことです。

これを使って書くと、Pythonの help() 関数で説明を表示させたり、専用のツールで自動的にドキュメントを作成したりすることができるようになります。

def calculate_bmi(weight, height):
    """
    体重と身長からBMI（体格指数）を計算します。

    Args:
        weight (float): 体重(kg)
        height (float): 身長(m)

    Returns:
        float: 計算されたBMI値
    """
    return weight / (height ** 2)

【Hiroki】 すごい！これはただのメモじゃなくて、本格的な「説明書」をコードの中に組み込めるということですね。

【Yuki】 はい。誰かが自分の作ったツールを使おうとした時、こうして丁寧に使い方が書いてあったら、きっと安心してもらえるはずです……。

自分一人で書いているプログラムでも、将来の自分は「他人」のようなものですから、docstringを書いておくと、後できっと自分に感謝されると思いますよ。

【Hiroki】 「将来の自分は他人」……。確かにそうですね。早速、関数を作る時はdocstringを意識してみます！

コメントアウト：デバッグのための強力な味方

【Yuki】 もう一つ、初心者の方にぜひ覚えておいてほしいコメントの使い道があります。それが「コメントアウト」です。

プログラムの中で、一時的に実行したくないコードの行を # でコメントにしてしまう手法のことです。

【Hiroki】 あ、それやってみたことがあります！エラーが出る場所を特定するために、怪しいところをコメントにして動かしてみたり……。

【Yuki】 正解です。不具合の原因を探す「デバッグ」の作業では、とてもよく使われます。

# print("古いデバッグ用の出力")
print("新しいロジックの実行結果:", result)

ただし、注意点があります。役目を終えたコメントアウトされたコードは、「消す」勇気も必要です。

いつまでも「古いコード」がコメントのまま残っていると、後から見た人が「これは必要なのかな？消してもいいのかな？」と不安になってしまうかもしれませんから……。

【Hiroki】 ついつい「後で使うかも」と思って残しがちですが、コードを綺麗に保つのも大切なんですね。気をつけます！

良いコメントを書くための、ちょっとしたコツ

【Yuki】 Hiroki君なら、きっと読みやすいコードを書けるようになると思います。

ここで、もう少しだけ踏み込んで、「良いコメント」とは何かについて考えてみましょう。

わたしは、一番良いコードというのは、「コメントがなくても意味が通じるコード」だと思っています。

【Hiroki】 えっ、コメントは大事だって言ったのに、ない方がいいんですか……？

【Yuki】 ふふ、少し矛盾しているように聞こえますよね。

例えば、変数の名前に a や b ではなく、user_age や total_price といった分かりやすい名前をつければ、わざわざ # ユーザーの年齢 と書く必要はなくなりますよね。

# 悪い例
d = 86400  # 1日の秒数

# 良い例
SECONDS_PER_DAY = 60 * 60 * 24

このように、コード自体を読みやすくすることを「自己文書化（Self-documenting）」と言います。まずはコードを分かりやすく書き、それでも説明が必要な「理由」や「背景」をコメントで補うのが、一番美しい形かな……と、わたしは思います。

【Hiroki】 なるほど！まずはコード自体で語らせて、コメントはそれを支える脇役、というイメージでしょうか。

【Yuki】 その通りです。脇役ではありますが、決して欠かせない存在……。

特に、「なぜこの数値を使っているのか」「なぜこの特殊な処理が必要だったのか」といった、コードからは読み取れない「意図」をコメントに残すようにしてみてください。

例えば、ライブラリのバグを回避するためにあえて変な書き方をしている場合などは、その理由をコメントで書いておかないと、後で他の人が「間違っている」と思って修正してしまい、またバグが発生する……なんて悲劇も起こり得ますから。

【Hiroki】 それは怖いですね……。そんな時に「道標」としてのコメントがあれば、悲劇を防げるわけですね。

PEP 8に学ぶ、コメントの書式ルール

【Yuki】 最後に、Pythonの標準的なルールである PEP 8 で定められている、コメントの書き方のマナーをいくつか紹介しますね。

これらを守ることで、世界中のPythonプログラマーにとって読みやすい、整ったコードになります。

1. インラインコメントの間隔: コードと同じ行にコメントを書くときは、コードとの間に少なくとも 2つのスペース を入れることが推奨されています。

   x = x + 1  # カウンタを増やす
   

2. コメントの文体: コメントは完全な文章であることが望ましいとされています。最初の文字は大文字で始め（英語の場合）、句読点で終わるのが丁寧です。

3. 古い情報の更新: コードを修正したときは、必ずコメントも一緒に更新してください。コードの内容と矛盾したコメントほど、読む人を混乱させるものはありません。

4. 言語の選択: もし、世界中の人に使ってもらうようなオープンソースのツールを作るなら、コメントは英語で書くのが一般的です。でも、個人の学習や日本国内のチーム開発なら、分かりやすい日本語で書くのが一番だと思います。

【Hiroki】 2つスペースを空ける、なんて細かいルールまであるんですね。でも、そういう細かい積み重ねが、綺麗なコードに繋がるんだろうな……。

【Yuki】 はい。フォントの並びが整っていると気持ちいいのと同じように、コメントの書式が整っていると、プログラム全体がとても洗練されて見えるものです。

プログラミングは、コンピューターへの命令であると同時に、人間同士のコミュニケーションでもある……。わたしは、そんな風に感じています。

【Hiroki】 コミュニケーション、ですか。なんだか素敵ですね。

今日学んだことを活かして、未来の自分や、いつか僕のコードを見てくれる誰かのために、優しくて分かりやすいコメントを書けるようになりたいと思います！

【Yuki】 その意気込み、とても素晴らしいと思います。Hiroki君の書くコードが、誰かを助ける温かいツールになることを願っていますね。

もし書き方に迷ったら、いつでも聞いてください。わたしも、少しでもあなたの力になれるよう、ここで支えていますから……。

今日は遅くまでお疲れ様でした。ゆっくり休んでくださいね。

【Hiroki】 ありがとうございます、Yukiさん！おやすみなさい！

参考資料

• Python スタイルガイド (PEP 8) - コメント
• Python チュートリアル - ドキュメンテーション文字列
• Python公式ドキュメント - 制御構造（コメントについて）