コメントで意図を残す
コメントで意図を残す とは
Python のコメント記法を学んで、コードに「なぜ」を残す習慣を身につけよう。本レッスンでは、コメントで意図を残す の基本から実際の使いどころまでを整理し、現場で迷わず使える形に落とし込みます。
コメントは「未来の自分」への手紙
コードを書いていると、「なぜここでこの計算をしているのか」が 1 ヶ月後の自分には全く思い出せない、ということがよく起こります。Python には、実行されないテキスト = コメント を書く文法が用意されていて、これがコードの意図を残すための最強のツールです。
良いコードとは、書き手が消えても他人が安全に触れるコード。コメントはそのために必須の習慣です。
Python のコメント記法
Python のコメントは # から行末までです。とてもシンプルで、行の途中からでも書けます。
Python
# これは行全体がコメント
x = 10 # 行末コメントも OK
# x = 20 # コメントアウトされた行は実行されない複数行コメントの専用文法はありませんが、# を各行の頭に付けて並べる、もしくは三重クオート """...""" の文字列を「捨てる」形で書く、という慣習があります。後者は厳密にはコメントではなく文字列リテラルですが、関数の説明用に docstring として広く使われています。
Python
def add(a, b):
"""a と b を足した値を返す関数."""
return a + b
docstringはhelp(add)で表示されたり、Sphinxなどのツールでドキュメント生成に使われたりします。単なるコメントよりも一段強力です。
何を書くか — what より why
コメントで陥りやすい罠は、「コードがやっていること (what)」をそのまま日本語に翻訳してしまうことです。
Python
# i に 1 を足す
i = i + 1これは情報量がほぼゼロです。コードを読めば誰でも分かる内容を、わざわざ書く必要はありません。代わりに、なぜ その処理が必要なのかを書きましょう。
Python
# 表示は 1 始まりにしたいので、0 始まりの index を補正
i = i + 1これなら、後から読んだ人が「ああ、表示用なのね」と理解できます。コメントは why を書く、これが鉄則です。
動きを追ってみる
コードとコメントの関係をイメージしておきましょう。
インタプリタにとってコメントは存在しないも同然ですが、人間にとってはコードと同じくらい重要な情報源です。実行コストはゼロなので、必要だと思ったら遠慮なく書きましょう。
よくある間違い
コメントについて初学者がやりがちなパターンは、次の通りです。
- 嘘のコメントが残っている (コードを直したのにコメントは古いまま)
- コードと同じ内容を日本語で書いただけのコメント
- TODO だけ書いて永遠に放置
#を全角の＃で書いてSyntaxError
特に「嘘のコメント」は最悪で、コメントを信じた後任者がバグを埋め込む原因になります。コードを修正したらコメントも合わせて更新する、これは絶対のルールです。
コメントは「書いて終わり」ではなく、コードと一緒に保守する対象です。
もう 1 つ覚えておきたいのが、# TODO: ... # FIXME: ... # NOTE: ... という慣習的なマーカーです。多くのエディタがこれらをハイライト表示してくれるので、後で対応すべき箇所を可視化するのに便利です。
Python
def parse_date(s):
# TODO: タイムゾーンを考慮する。今は UTC 固定。
return sやってみよう
このレッスンの課題は、コメント付きで a と b の合計を返す add_with_comment 関数を書くことです。動作自体は単純な足し算ですが、関数の上に 何のための関数か を 1 行コメントで書き、return の上には どんな計算をしているか を補足するコメントを書いてみましょう。
Python
# a と b の合計を返すユーティリティ関数
def add_with_comment(a, b):
# 単純な足し算だが、レッスン課題用にコメントを残す
return a + bコメントの有無は採点に影響しませんが、習慣として why を残す癖をつけるための演習です。慣れてきたら、docstring も書いてみるとさらに本格的です。
Python
def add_with_comment(a, b):
"""a と b の合計を返す.
レッスン課題用のシンプルな例。
"""
return a + b「読みやすいコードを書く」は、
Pythonの理念The Zen of Pythonの中でも繰り返し強調されています。コメントはその第一歩。
コメントを書ける人と書けない人では、3 年後のコードの読みやすさが天と地ほど違います。最初のうちから「未来の自分への手紙」を残す習慣を身につけましょう。
おまけ — コメントアウトのテクニック
開発中に「この行をいったん無効化して動きを確かめたい」というケースは頻繁にあります。そんなときに使うのが コメントアウト です。行頭に # を足すだけで、その行を実行されないテキストに変えられます。
Python
# 旧バージョンの計算式 (新仕様で不要になったが念のため残す)
# total = price + price * 0.08
total = price + price * 0.10多くのエディタには「選択範囲をまとめてコメントアウト/解除」のショートカットがあります。VSCode なら Cmd + / (Mac) または Ctrl + / (Windows) です。1 行ずつ # を付けるのではなく、ショートカットを使うクセを早めにつけておきましょう。
ただし、長期間「コメントアウトしたまま放置されたコード」は混乱の元です。Git のバージョン管理で履歴を残せるので、不要になったコードは原則として削除します。
よくある質問
Q. このトピックは Python 以外の言語でも同じ書き方ですか？
A. 考え方は他言語と共通ですが、構文や標準ライブラリは異なります。Python はインデントでブロックを表し、コロン + 改行で構造を作るのが特徴です。他言語に移行する際は基本概念を維持しつつ、構文の差分を意識して書き換えると混乱が少ないです。
Q. 実行してエラーが出た場合の対処は？
A. エラーメッセージの最後の行（TypeError や NameError などの型）から原因と該当行を確認します。Python はトレースバックが下から上に読むと「呼び出し元 → 内部」の順で辿れます。print や IDE のデバッガで途中の変数を確認すると原因が見えてきます。
Q. 次のステップで何を学ぶべきですか？
A. 本レッスンの内容を理解できたら、本文の「やってみよう」を実装し、章末クイズに進むのがおすすめです。さらに自分のミニアプリ（電卓・todo・スコア集計など）に応用するとスキルが定着します。詰まったら本文の H2 セクションに戻って読み返してください。
次のレッスン
次は 商と余りを一度に求める で、Python のコメント記法を学んで、コードに「なぜ」を残す習慣を身につけよう を学びます。
事前確認 — 進む前に次の 3 つができることを確認しましょう。
- コメント の要点を自分の言葉で説明できる
- このレッスンの最小コード (または操作手順) を見ずに書ける
- 練習問題やクイズで間違えた箇所を読み直して理解した
理解度チェック (30 秒)
Q. コメント とは何か、1 文で説明してください。
A. 本文の「このレッスンで分かること」または冒頭の説明文を見直し、自分の言葉で要約できれば OK。詰まったら本レッスンの最初の H2 セクションを読み返してみましょう。
関連レッスン
要件
- 関数名は add_with_comment、引数は a と b
- a と b の合計を return する
- コード中に最低 1 行のコメントを書く
入出力例
test-cases.txt
add_with_comment(2, 3) → 5
add_with_comment(0, 0) → 0
add_with_comment(-5, 3) → -2