【Python】コメントの書き方を徹底解説！これだけでコードが見違える

Pythonのコメントの書き方、ちゃんと理解していますか？

「まあ、#つければいいんでしょ？」くらいに思っていると、後で自分が書いたコードが読めなくなったり、他の人を混乱させたりしちゃうかも！

この記事では、Pythonのコメントの基本的な書き方から、思わず「なるほど！」と膝を打つような実践的な使い方、そして「これはやっちゃダメ！」な注意点まで、全部まとめて解説します。

この記事で学べること

コメントを書く本当の意味
基本的なコメントの書き方（2種類！）

* コードを一時的に無効にするコメントアウトの方法

読みにくいコメントを避けるための注意点

ちょっと特別なコメント「docstring」の基本

Pythonにおけるコメントの重要性とは？なぜ書く必要があるのか

「コメントなんて書かなくても、コードが動けばいいじゃん！」

って思う気持ち、すごくよく分かります。

でも、ちょっと想像してみてください。

1ヶ月前に自分が書いた、ちょっと複雑なコード。今見返して、すぐに「あー、ここはこういう意図で書いたんだった！」って思い出せますか？

他の人があなたのコードを見て、すぐに理解できるでしょうか？
もし、コメントがなかったら…

コードの解読に時間がかかる
まるで古代の暗号文を解くみたいになっちゃうかも。
バグの原因特定が難しくなる
どこで何をしているか分からないと、修正も大変です。
他の人が協力しにくい
チーム開発だと、コメントがないと作業がストップしちゃうことも。
未来の自分が困る
「なんでこんな書き方したんだっけ…？」って頭を抱えることになります。これは本当に辛い！

コメントは、コードの「取扱説明書」みたいなものなんです。

書くのは少し手間かもしれませんが、それ以上にコードの分かりやすさ（可読性）や、後からの修正しやすさ（保守性）をグーンとアップさせてくれる、縁の下の力持ちなんですよ。

面倒くさがらずに、未来の自分や仲間たちのために、ちょっとだけ手間をかけてみませんか？

コメントの基本的な書き方 - まずは2種類を覚えよう

Pythonでコメントを書く方法は、大きく分けて2つあります。
難しくないので、まずはこの2つの基本形をサクッと覚えちゃいましょう！

シャープ記号を使ったシングルラインコメントの書き方

一番よく使うのが、このシャープ記号（#）を使ったコメントです。

「#」を書くと、その行の「#」以降の文字は、プログラムの実行時には無視されます。つまり、コンピュータにとっては存在しないものとして扱われるんです。

主に、1行で完結する短い説明やメモを残すのに使います。

# これは1行コメントの例です
x = 10  # ここから右側がコメント。変数xに10を代入しているよ！

print(x) # 変数xの中身を表示する

コードのすぐ横に書いて、その行が何をしているかを補足説明する（インラインコメント）こともできます。

ただし、あまりにも当たり前のことを書くと、かえってコードが読みにくくなることもあるので注意してくださいね。

クォーテーションマーク3つを使ったマルチラインコメントの書き方

複数行にわたってコメントを書きたい場合は、シングルクォーテーション3つ（'''）またはダブルクォーテーション3つ（"""）でコメントしたい部分を囲みます。

厳密には、これはコメント専用の機能ではなく「複数行にわたる文字列」を作るための書き方なのですが、結果的にプログラムからは無視される（どこにも代入したり使ったりしなければ）ので、コメントとしてよく利用されます。

'''
これは複数行コメント（マルチラインコメント）の
書き方の例です。
このように、改行しても大丈夫！
'''

"""
ダブルクォーテーション3つでも
同じように書けます。
どっちを使うかは、好みやプロジェクトのルールによります。
"""

x = 5
y = 10
'''
z = x + y  # この行を一時的に実行したくない場合
print(z)   # この行も実行したくない
'''
print("ここは実行されるよ")

この書き方は、関数の説明を詳しく書いたり、コードの一部を一時的に実行しないようにしたり（コメントアウト）する時によく使われます。

シングルクォート（'）とダブルクォート（"）のどちらを使うかは、機能的な違いはほとんどありません。プロジェクトやチームでルールが決まっている場合はそれに従いましょう。

なければ、どちらか一方に統一しておくと見た目がスッキリします。

コメントはどこに何を書くべきか？効果的な書き方

基本的な書き方が分かったところで、次は「じゃあ、具体的にどんなことをコメントとして書けばいいの？」という疑問に答えていきましょう。

コメントは、ただ闇雲に書けばいいわけではありません。効果的なコメントは、コードの理解を助けますが、意味のないコメントは逆に邪魔になることも。

大事なのは、「コードだけを見ても分かりにくい情報」を補うことです。

原則として、コードを読めばすぐに分かるようなことは書かないようにしましょう。

# 悪い例: コードを見ればわかることを書いている
# iに1を加える
i = i + 1

# 良い例: なぜそうするのか、意図を書いている
# ループのカウンターを次に進める
i = i + 1

コメントで書くべきなのは、主に次のような情報です。

コードの「なぜ」（Why）なぜこの処理が必要なのか、なぜこの方法を選んだのか
複雑な処理の概要
コードを使う上での注意点や前提条件

これから、具体的な書き方を例と共に見ていきましょう。

コードの意図や背景を伝えるコメントの書き方

プログラムを書いていると、「なんでこんな回りくどい書き方してるんだろう？」とか「普通はこう書くんじゃないの？」と思うようなコードに出会うことがあります。

そういうコードには、多くの場合、何か理由があります。

例えば、特定の条件下で発生するバグを避けるためだったり、パフォーマンスを改善するための特別な工夫だったり。

そういった、コードを見ただけでは分からない「背景」や「意図（なぜそう書いたのか）」をコメントで説明してあげると、他の人（そして未来の自分！）がコードを理解するのを大きく助けます。

# なぜこの変数が必要なのか、理由を説明する
attempts = 0 # 接続試行回数を記録する（最大3回まで）

while attempts < 3:
    # ... 接続処理 ...
    if connection_successful:
        break
    else:
        # なぜここで1秒待つのか説明する
        time.sleep(1) # サーバー負荷軽減のため、再試行前に1秒待機
        attempts += 1

「なぜ？」を説明するコメントは、コードの可読性を格段に向上させます。

複雑なロジックやアルゴリズムの要約コメント

何十行、何百行にもわたる関数や、ちょっと難しいアルゴリズムを実装した場合、コードを一行一行追っていくのは大変ですよね。

そんな時、処理全体の流れや、使っているアルゴリズムの概要をコメントで最初に示しておくと、読む人はまず全体像を掴んでから詳細に入ることができます。

料理で言えば、レシピの最初に「材料を切る→炒める→煮込む」といった大まかな流れが書いてあるようなイメージです。

def process_user_data(user_id):
    """
    ユーザーデータを処理する関数

    処理の流れ:
    1. ユーザーIDから基本情報を取得
    2. 過去の行動履歴を取得
    3. 基本情報と行動履歴を元に、おすすめ商品を計算
    4. 結果をデータベースに保存
    """

    # 1. ユーザーIDから基本情報を取得
    user_info = get_user_info(user_id)
    if not user_info:
        return None # ユーザーが見つからない場合はNoneを返す

    # 2. 過去の行動履歴を取得
    # ここでは、複雑な集計処理を行っているとする
    action_history = aggregate_action_history(user_id)

    # 3. おすすめ商品を計算（独自のレコメンドアルゴリズムを使用）
    recommendations = calculate_recommendations(user_info, action_history)

    # 4. 結果をデータベースに保存
    save_recommendations(user_id, recommendations)

    return recommendations

このように、複雑な処理の「地図」を示すコメントがあると、コードの森で迷子になりにくくなります。

注意事項やTODO備忘録としてのコメント活用法

コードを書いていると、「ここは後で直したいな」とか「この部分は、こういう使い方をすると問題が起きるかも」といったメモを残しておきたくなることがあります。

そんな時に便利なのが、特定のキーワードを使ったコメントです。これらは慣習としてよく使われていて、後でコードの中から検索しやすいというメリットもあります。

# TODO: (トゥードゥー) まだ実装していない機能や、後でやるべき作業があることを示します。
# FIXME: (フィックスミー) コードに問題（バグ）があることが分かっていて、修正が必要な箇所を示します。
# XXX: (エックスエックスエックス) 注意が必要な箇所や、少しトリッキーな実装について注意喚起する時に使われます。

def calculate_discount(price, user_rank):
    if user_rank == "gold":
        # FIXME: 消費税の計算が現在の仕様と合っていない可能性がある
        discount_rate = 0.1
    elif user_rank == "silver":
        discount_rate = 0.05
    else:
        # TODO: ブロンズランク向けの割引も将来的に追加する
        discount_rate = 0.0
    
    # XXX: priceがマイナスの場合の考慮がされていない
    return price * discount_rate

# TODO: 関数のテストコードを書く

これらの特別な目印コメントは、自分自身への備忘録として、またチームメンバーへの情報共有として役立ちます。

Pythonのコメントアウトでコードを一時的に無効化する方法

プログラムを書いていると、

「この部分、ちょっと動かしてみて問題ないか確認したいんだけど、他の部分は一旦止めておきたいな…」
とか、
「この処理、今は使わないけど後でまた使うかもしれないから消したくないな…」
という場面がよくあります。

そんな時に使うテクニックが「コメントアウト」です。

これは、コードの一部をコメントにしてしまうことで、プログラム実行時にその部分を無視させる方法です。

# 例1: 1行だけコメントアウト
x = 10
# y = 20  # この行は実行されない
z = 30
# print(y) # この行も実行されない
print(x + z)

# 例2: 複数行をまとめてコメントアウト
'''
print("ここから")
print("ここまで")
print("実行したくない")
'''
print("ここは実行される")

"""
ダブルクォーテーションでもOK
a = 1
b = 2
print(a * b)
"""
print("こっちも実行される")

コメントアウトは、デバッグ（バグ探しや修正）の際に非常に役立ちます。

多くのコードエディタ（プログラムを書くためのソフト）には、選択した範囲を一気にコメントアウトしたり、元に戻したりするショートカットキーが用意されていることが多いです。（例えば Ctrl + / や Command + / など）

これを覚えておくと、作業効率が格段にアップしますよ！

読みやすいコメントを書くための注意点とコツ

さて、コメントの書き方や使いどころが分かってきたところで、今度は「良いコメント」を書くための注意点やコツについてお話しします。

せっかくコメントを書いても、それが分かりにくかったり、間違っていたりすると、逆効果になってしまうこともありますからね。

以下の点に気をつけて、読み手にとって本当に役立つコメントを目指しましょう！

コードで分かることは書かない
当たり前のことをコメントで繰り返すと、コードがごちゃごちゃして読みにくくなります。
コメントは常に最新の状態に保つ
コードを修正したら、関連するコメントも必ず見直して修正しましょう。古いコメントは嘘をつくことになり、混乱の元です！
簡潔に、分かりやすく
ダラダラと長い説明は避け、要点を絞って書きましょう。
コメントのスタイルを統一する
特にチームで開発する場合は、コメントの書き方（例 #の後にスペースを入れるか、インデントはどうするか等）を揃えると、コード全体に統一感が出て読みやすくなります。
ネガティブなコメントは避ける
「このコードはひどい」のようなコメントは、何の助けにもなりませんし、雰囲気も悪くなります。

# 悪い例: コードを見ればわかるし、ちょっと冗長
# 変数 "total_price" に 100 を設定する
total_price = 100

# 悪い例: 古いコメント（もしかしたら以前は消費税8%だったのかも？）
# 消費税8%を計算
tax = total_price * 0.1 # 現在の消費税率10%

# --- 改善例 ---

# 商品の合計金額（税抜）
total_price = 100

# 消費税額を計算（税率10%）
tax = total_price * 0.1

コメントもコードの一部という意識を持って、丁寧にメンテナンスしていくことが大切です。

Pythonのdocstringドキュメンテーション文字列とは

Pythonには、通常の「#」コメントとは別に、「docstring（ドックストリング）」と呼ばれる特別なコメント（正確には文字列リテラル）があります。

これは、関数、クラス、モジュール（Pythonファイル）の定義の直後に書かれる、`'''` または `"""` で囲まれた文字列のことです。

docstringの主な目的は、その関数やクラスなどが「何をするものなのか」「どうやって使うのか」といった説明書（ドキュメント）の役割を果たすことです。

def add(a, b):
  """二つの数を受け取り、その合計を返す関数です。

  Args:
    a: 一つ目の数値
    b: 二つ目の数値

  Returns:
    aとbの合計値
  """
  return a + b

# help()関数でdocstringを確認できる
help(add)

docstringを書いておくと、次のようなメリットがあります。

help()関数で、その関数やクラスの使い方が表示される。
Sphinxなどのツールを使って、プログラムの説明書（ドキュメント）を自動生成できる。
他の人があなたのコードを使うときに、何をするものなのか理解しやすくなる。

ライブラリやフレームワークなど、他の人に使ってもらうことを想定したコードを書く場合、docstringは非常に有効です。

書き方にはいくつかのスタイル（Googleスタイル、NumPyスタイルなど）がありますが、まずは基本的な構成を覚えておくと良いでしょう。

簡単なdocstringの書き方と具体例

docstringの書き方に厳密なルールがあるわけではありませんが、一般的にはPEP 257というガイドラインで推奨されている書き方が参考になります。

ここでは、シンプルな関数の例で、基本的なdocstringの書き方を見てみましょう。

def greet(name):
  """指定された名前を使って挨拶メッセージを作成します。

  関数は、受け取った名前に "Hello, " と "!" を付けて返します。
  例えば、"Alice" を渡すと "Hello, Alice!" が返されます。

  Args:
    name (str): 挨拶する相手の名前（文字列）。

  Returns:
    str: 生成された挨拶メッセージ（文字列）。
  """
  if not isinstance(name, str):
      # 簡単なエラー処理の例
      return "Error: name must be a string" 
  return f"Hello, {name}!"

# docstringを使ってみる
message = greet("Bob")
print(message)

# help関数で確認
help(greet) 
# 以下のような出力が得られるはずです（環境によって多少異なります）
# Help on function greet in module __main__:
# 
# greet(name)
#     指定された名前を使って挨拶メッセージを作成します。
#     
#     関数は、受け取った名前に "Hello, " と "!" を付けて返します。
#     例えば、"Alice" を渡すと "Hello, Alice!" が返されます。
#     
#     Args:
#       name (str): 挨拶する相手の名前（文字列）。
#     
#     Returns:
#       str: 生成された挨拶メッセージ（文字列）。

基本的な構成は以下のようになります。

1行目要約行：関数やクラスの目的を簡潔に書きます。動詞で始めることが多いです。
空行：1行目の要約と詳細説明の間に空行を入れます。
詳細説明（任意）：必要であれば、より詳しい説明、使い方、注意点などを書きます。
引数（Args）：関数が受け取る引数について、名前、型、説明を書きます。
返り値（Returns）：関数が返す値について、型と説明を書きます。

docstringをしっかり書く習慣をつけておくと、コードの再利用性やメンテナンス性が格段に向上しますよ！

Pythonのコメントに関するよくある疑問を解消

ここまでPythonのコメントについて色々解説してきましたが、もしかしたらまだ「これはどうなんだろう？」と疑問に思う点があるかもしれません。

ここでは、初心者の人が特に疑問に思いがちな点をいくつかピックアップして、Q&A形式でお答えします！

コメントは日本語と英語どちらが良いのか

Q: コメントって、日本語で書いてもいいの？それとも英語じゃないとダメ？

A: 結論から言うと、状況によります！ 絶対的な正解はありません。
判断基準としては、そのコードを「誰が読むか」を考えるのが良いでしょう。

自分だけで使うコード、日本人だけのチームで使うコード
この場合は、日本語で書くのが分かりやすいことが多いです。無理に英語で書く必要はありません。母国語の方が、微妙なニュアンスも伝えやすいですよね。
海外の人も関わるプロジェクト、公開するライブラリなど
この場合は、英語で書くのが一般的です。世界中の多くの開発者が英語を共通言語として使っているため、英語で書いておけば、より多くの人に読んでもらえる可能性が高まります。有名なPythonライブラリのコードも、ほとんどが英語でコメントされています。

もしチームで開発しているなら、最初に「コメントはどっちの言語で書こうか」とルールを決めておくのがおすすめです。

途中で日本語と英語が混在すると、かえって読みにくくなることがありますからね。

コメントの適切な量どれくらい書けば良いのか

Q: コメントって、たくさん書けば書くほど良いの？目安とかある？

A: いいえ、必ずしも「量が多ければ良い」というわけではありません！ 大事なのは量よりも「質」です。
コメントの目的は、コードの理解を助けること。だから、書くべきなのは「コードだけでは分からない情報」です。

コメントが少なすぎる場合
コードの意図が分からず、読む人が苦労します。特に複雑な処理や、なぜその書き方にしたのか理由がある場合は、コメントがないと解読不能になることも。
コメントが多すぎる場合
コードを見れば分かるような当たり前のことまでコメントで書いてあったり、ダラダラと長い説明が続いていたりすると、コードを読む邪魔になります。コメントばかりで、肝心のコードが埋もれてしまうことも。

目指すべきは、「必要十分な量」です。

「このコメントは、本当にコードの理解を助けているかな？」「この説明がないと、他の人（や未来の自分）は困るかな？」と考えながら書くのがコツです。

そして、コメントを書く前に、「もっと分かりやすい変数名や関数名にできないか？」「コードの構造をもっとシンプルにできないか？」と考えて、コード自体を改善する努力も、同じくらい大切ですよ。

【まとめ】Pythonのコメントを使いこなして読みやすいコードを書こう

この記事では、Pythonのコメントについて、基本的な書き方から実践的な使い方、注意点、そしてdocstringまで、幅広く解説してきました。

もう一度、大事なポイントを振り返っておきましょう。

コメントはコードの可読性と保守性を高める重要な要素！
基本は `#` (シングルライン) と `'''` or `"""` (マルチライン/docstring) を使い分ける。
「なぜ(Why)」や「複雑な処理の概要」など、コードだけでは分からない情報を書く。
コードで分かることは書かない。コメントは常に最新に保つ。
コメントアウトはデバッグの強い味方！
docstringは関数やクラスの説明書。他の人が使うコードには特に有効。

コメントは、単なるおまけではありません。優れたコードを書く上で、絶対に欠かせないスキルの一つです。

最初は少し面倒に感じるかもしれませんが、分かりやすいコメントを書く習慣をつけることで、あなたのコードは劇的に改善され、プログラミングがもっと楽しく、効率的になるはずです。

【関連記事】 「Pythonとは？」に答える最初の一歩

Pythonコメントの書き方を徹底解説！これだけでコードが見違える