ここからは「複数行コメント（ドキュメンテーションコメント）」と「コメントのベストプラクティス」について、初心者向けに丁寧に解説しますね。
複数行コメント（ドキュメンテーションコメント）
1. 複数行コメントの書き方
Pythonには「専用の複数行コメント構文」はありません。
ただし、文字列リテラル（""" ... """ や ''' ... '''）を使って複数行の説明を書くのが一般的です。
"""
このプログラムはBMIを計算します。
- 身長と体重を入力
- BMIを計算
- 結果を表示
"""
このように書くと、実行時には無視されるので「複数行コメント」として使えます。
2. ドキュメンテーション文字列（docstring）
特に関数やクラスの説明には、""" ... """ を使うのが推奨されています。これを docstring（ドックストリング） と呼びます。
def calc_bmi(height, weight):
"""
BMIを計算する関数
height: 身長(cm)
weight: 体重(kg)
return: BMI値
"""
return weight / (height/100) ** 2
print(calc_bmi(160, 50))
👉 help(calc_bmi) とすると、このdocstringが表示されます。
つまり「関数の説明書」として役立つんです。
コメントのベストプラクティス
1. 「なぜ」を書く
- コードが「何をしているか」は見ればわかることが多いです。
- コメントでは「なぜこの処理をしているのか」を書くと、後で読み返したときに役立ちます。
# 小数点以下を切り捨てるのは、金額計算で誤差を避けるため
price = int(99.9)
2. 過剰に書かない
- すべての行にコメントを書くと逆に読みにくくなります。
- 「重要な部分」「意図が伝わりにくい部分」に絞って書きましょう。
❌ 悪い例：
# 変数aに1を代入
a = 1
# 変数bに2を代入
b = 2
# aとbを足す
c = a + b
⭕ 良い例：
# aとbを足して合計を求める
a, b = 1, 2
c = a + b
3. コメントは最新に保つ
- コードを修正したら、コメントも更新しましょう。
- 古いコメントは誤解を招くので、ない方がマシです。
4. Docstringを活用する
- 関数やクラスにはdocstringをつける習慣を持つと、他人にも自分にも優しいコードになります。
まとめ
- 複数行コメントは
""" ... """を使う - docstring は関数やクラスの説明に必須
- コメントは「なぜ」を書く
- 過剰に書かず、最新の状態に保つ