プログラミングを学ぶ上で、コードをただ動かすだけでなく、他の人や未来の自分が理解しやすいように書くことは非常に重要です。
Pythonでは「コメント」を使ってコードに説明を加えることで、可読性を高め、バグの原因を見つけやすくなります。
本記事では、初心者向けにPythonのコメントの基本からベストプラクティスまでを解説し、最後に演習問題と解答例を紹介します。
コメントとは何か
コメントとは、プログラムの実行には影響しないテキストで、コードの目的や処理の流れ、注意点などを記述します。コメントを適切に使うことで、以下のメリットがあります。
- 可読性の向上：処理内容がひと目で分かる
- 保守性の向上：後から見直したときに理解しやすい
- チーム開発の円滑化：他のメンバーがコードを理解しやすい
コメントの種類
Pythonでは主に以下の2種類のコメントを使います。
シングルラインコメント
行頭に # を置く方法です。単一行の説明を付けたいときに使います。
# 変数xに1を代入
x = 1ブロックコメント（複数行コメント）
複数行にわたってコメントを記述したい場合、各行に # を付けるか、文字列リテラルを利用します。
ただし、文字列リテラルは厳密にはコメントではなくドキュメンテーション文字列（docstring）として扱われるため、注意が必要です。
# これは
# 複数行にわたる
# コメントですまたは
"""
この関数はユーザー情報を取得し、
辞書形式で返します。
"""
def get_user_info(user_id):
...ドキュメンテーション文字列（docstring）
関数やクラスの先頭に置く三重引用符 “”” または ”’ を使った文字列をdocstringと呼び、Pythonのリフレクション機能で取得可能です。APIドキュメントの自動生成ツール（Sphinxなど）でも活用されます。
def greet(name):
"""
名前を受け取り、挨拶メッセージを返す関数
Args:
name (str): 挨拶する相手の名前
Returns:
str: 挨拶メッセージ
"""
return f"Hello, {name}!"コメントのベストプラクティス
過剰なコメントは避ける
コードの意図が明らかな場合、コメントは不要です。
冗長なコメントはかえって可読性を損なうことがあります。
# iを1ずつ増やす
for i in range(5): # 不要なコメント
print(i)変更時にコメントを更新する
コードを修正したら、コメントも必ず見直しましょう。
実際の処理とコメントがずれていると混乱の原因になります。
英語と日本語の使い分け
プロジェクトによっては英語コメントが求められる場合があります。
国際的な開発やオープンソースに参加する場合は、英語で書く練習をしましょう。
TODOやFIXMEの活用
未実装の箇所や要修正箇所には # TODO: や # FIXME: を付けると便利です。IDEやコード解析ツールで一覧表示でき、管理が楽になります。
# TODO: エラー処理を追加する
def fetch_data():
pass実際のコード例
以下に、コメントを適切に使ったサンプルコードを示します。
import math
class Circle:
"""
円を表すクラス
Attributes:
radius (float): 円の半径
"""
def __init__(self, radius):
# 半径をセット
self.radius = radius
def area(self):
"""
円の面積を計算して返す
Returns:
float: 計算された面積
"""
# 面積 = π × 半径^2
return math.pi * self.radius ** 2
# メイン処理
if __name__ == "__main__":
c = Circle(5)
print(f"半径5の円の面積: {c.area()}")演習問題
問題1：シングルラインコメントの追加
次のコードに、各処理の説明コメントを追加してください。
numbers = [1, 2, 3, 4, 5]
squared = []
for n in numbers:
squared.append(n ** 2)
print(squared)問題2：docstringの作成
次の関数にdocstringを追加し、引数と戻り値を説明してください。
def multiply(a, b):
return a * b問題3：TODOコメントの活用
未実装の関数 process_data に # TODO: コメントを追加し、実装すべき内容を明示してください。
def process_data(data):
pass解答例
解答1
# 元の数値リストを定義
numbers = [1, 2, 3, 4, 5]
# 平方を格納する空リストを用意
squared = []
# リスト内の各要素に対して平方を計算
for n in numbers:
# 計算結果をsquaredリストに追加
squared.append(n ** 2)
# 結果を表示
print(squared)解答2
def multiply(a, b):
"""
2つの数値を掛け合わせて返す関数
Args:
a (int or float): 乗算する最初の数値
b (int or float): 乗算する2番目の数値
Returns:
int or float: aとbの積
"""
return a * b解答3
def process_data(data):
# TODO: データを検証し、不要な要素をフィルタリングする処理を実装
# TODO: 前処理として欠損値の補完を行う
# TODO: 正規化やスケーリングを適用
passおわりに
コメントはコードの品質を大きく左右します。
初級編として本記事で学んだ基本を押さえ、実際の開発や学習で積極的にコメントを書いてみましょう。
慣れてきたら、自分なりのスタイルガイドを作成し、チームやオープンソースプロジェクトで共有するのもおすすめです。