コメントのアノテーション・タグ（キーワード）15選

はじめに

先日、仕事でコメント関連の話題になったので、備忘録を兼ねて。

プログラミングをしていると、コードにコメントを入れることが多いですよね。

小規模なうちは特に問題ないのですが、プロジェクトが大規模化・複雑化するにつれ、コードが持つ情報や簡易的なコメントだけでは、開発者間の円滑なコミュニケーションを維持することが難しくなります。

ここで重要な役割を果たすのが「コメントの書き方」です。
特に、# TODO や # FIXME といった特定のキーワード（アノテーション・タグ）を用いたコメントは、コードの現状、課題、設計意図などが分かりやすくなります。

本記事では、自分なりに集めたアノテーション・タグについて、それぞれの使用例を記載します。（間違いがあったらコメントください）
今回はPythonですが、他の言語でも同様に適用できます。

---

コメントのアノテーション・タグ

1. タスク管理と課題（TODO, FIXME, BUG）

開発プロセスにおける「やるべきこと」や「問題点」を管理するためのキーワード。

1.1. TODO: 将来実装すべきタスク

意味: 現時点では未実装だが、将来的に対応が必要な作業。

使用例:

# TODO(user_name): ユーザー認証が実装され次第、実際のユーザー情報を返すように修正する。 (Issue #123)
def get_user_profile(user_id: int) -> dict:
    """指定されたIDのユーザープロファイルを取得する（現在はダミー）"""
    return {"user_id": user_id, "name": "Dummy User"}

1.2. FIXME: 修正が必要な既知の問題

意味: 既知のバグ、または明らかに不適切・非効率で、修正が必須な箇所。TODO よりも緊急性が高いニュアンスを持つ。

使用例:

# FIXME: 'divisor' が 0 の場合に ZeroDivisionError を引き起こす。例外処理または事前チェックを追加する必要あり。
def calculate_ratio(total: float, divisor: float) -> float:
    return total / divisor 

1.3. BUG: 明確なバグの指摘

意味: FIXME よりも具体的に「機能的な欠陥」「誤った動作」を示す。

使用例:

# BUG: 'items' が空のリストの場合、インデックスエラーが発生 (Issue #456)
def get_last_item(items: list):
    if items: # BUG: このチェックでは不十分 (例: items=[])
        return items[-1]
    return None # 本来は空のリストでも None を返すべき

---

2. 設計意図と補足（NOTE, XXX, REVIEW）

コードの補足説明をするためのキーワード。

2.1. NOTE: 設計意図や補足説明

意味: コードを読むだけでは伝わりにくい設計上の意図、背景、または特定のライブラリや仕様に関する補足情報。

使用例:

# NOTE: ここで `time.sleep(0.5)` を挿入しているのは、外部APIのレートリミット (10 req/sec) を回避するため
def fetch_external_data():
    for i in range(20):
        # ... APIリクエスト ...
        time.sleep(0.5)

2.2. XXX: 未決定・要議論

意味: 実装方針が未定、あるいは最適な解決策が不明で、後で再検討や議論が必要な箇所。

使用例:

# XXX: 現在は通貨を 'JPY' にハードコードしている
#      多通貨対応の設計（例: i18nモジュールの利用）について、
#      次回の設計レビュー会議で議論が必要
def format_price(price: int) -> str:
    return f"¥{price:,}"

2.3. REVIEW: 再検討・議論の必要性

意味: 実装に自信がない、または他の開発者の意見を求めたい箇所。コードレビュー時に特に注目してほしいポイントを明示。

使用例:

# REVIEW: このロジックは、すべてのケースをカバーできているか？
#         @reviewer_name さん、ご意見ください
def process_complex_dict(data: dict):
    # ... 複雑な処理 ...

---

3. コード品質とリファクタリング（OPTIMIZE, REFACTOR, HACK）

コードの効率性や保守性に関するキーワード。

3.1. OPTIMIZE: 最適化の余地

意味: 機能的には動作するが、パフォーマンス（速度、メモリ効率）の面で改善の余地がある箇所。

使用例:

# OPTIMIZE: このループは、データ量によっては深刻なボトルネックになる
#           NumPyやPandasの利用、またはアルゴリズムの見直しを検討
def find_matches(list1, list2):
    matches = []
    for item1 in list1:
        for item2 in list2:
            if item1 == item2:
                matches.append(item1)
    return matches

# OPTIMIZE: 上記はリスト内包表記でも対応できるが、根本的な解決ではない
#           (例: return [item for item in list1 if item in set(list2)])

3.2. REFACTOR: リファクタリングの必要性

意味: OPTIMIZE がパフォーマンスに焦点を当てるのに対し、REFACTOR は設計の質（可読性、保守性、拡張性）の改善が必要な箇所。

使用例:

# REFACTOR: この関数は 300 行を超え、役割が多い（データ取得、バリデーション、加工、DB保存）
#           クラスや関数に分割すべき
def handle_user_registration(request_data):
    # ... 長い処理 ...

3.3. HACK: 一時的な回避策

意味: 理想的ではないが、特定の問題（ライブラリのバグ、納期の制約など）を回避するための一時的な解決策。

使用例:

# HACK: 依存ライブラリのバグを回避するため、3回までリトライ（暫定処置）
#       'some_lib==1.2.1' がリリースされ次第、これは削除する
def get_data_from_buggy_lib():
    for _ in range(3):
        result = some_lib.fetch()
        if result is not None:
            return result
        time.sleep(0.5)
    return None

---

4. 警告と履歴（WARNING, DEPRECATED, CHANGED）

コードの利用者に注意を促したり、変更の経緯を記録したりする。

4.1. WARNING: 潜在的な危険性

意味: コードの実行に伴う潜在的な危険性、重大な副作用、または制約。

使用例:

import pickle

# WARNING: 'pickle' は信頼できないデータをデシリアライズすると、
#          任意のコード実行の脆弱性を引き起こす
#          この関数には、信頼できるソースからのデータのみを渡すこと
def load_data_unsafe(serialized_data):
    return pickle.loads(serialized_data)

4.2. DEPRECATED: 非推奨（廃止予定）

意味: その関数やクラスが旧式であり、将来のバージョンで削除予定である。

使用例:

import warnings

# DEPRECATED: この関数は v3.0 で廃止予定
#             代わりに 'new_calculate_metrics_v2()' を使用してください
def old_calculate_metrics(data):
    warnings.warn(
        "'old_calculate_metrics' は非推奨です。"
        "'new_calculate_metrics_v2' を使用してください。",
        DeprecationWarning,
        stacklevel=2 # 呼び出し元で警告を表示させる
    )
    # ... 古いロジック ...

4.3. CHANGED: 変更履歴や経緯

意味: 特定の理由（仕様変更、バグ修正）によりコードが変更されたことを明示。

使用例:

# CHANGED: 2025-11-11 / 担当者名 (Issue #777)
#          旧仕様では文字列を返していたが、新仕様に基づき
#          処理結果のステータスコード (int) を返すよう変更
def process_request(request):
    # ...
    # return "Success" # 旧仕様
    return 200 # 新仕様

---

5. 高度な懸念事項（SECURITY, PERF, TEMP）

より専門的な領域（セキュリティ、パフォーマンス、一時的措置）に関するキーワード。

5.1. SECURITY: セキュリティ上の懸念

意味: 潜在的なセキュリティ脆弱性（SQLインジェクション、XSS、不適切な権限管理など）が存在する箇所、あるいはそれを意図的に防いでいる箇所。

使用例:

from django.db import connection

# SECURITY: ここで生SQLを使用しているが、'user_input' が適切にサニタイズされていない場合、SQLインジェクションの脆弱性となる
#           ORM (objects.filter) を使用する形にリファクタリングすること
def get_user_by_name(user_input):
    with connection.cursor() as cursor:
        cursor.execute("SELECT * FROM users WHERE username = '" + user_input + "'")
        # ...

5.2. PERF / PERFORMANCE: パフォーマンスへの言及

意味: OPTIMIZE よりも具体的に、計測されたボトルネックや、パフォーマンスに重大な影響を与える処理（例：重いI/O、ロック競合）。

使用例:

# PERF: プロファイリング結果 (2025-11-10) より、
#       この同期的なファイルI/Oがアプリケーション全体のボトルネックとなっている
#       'asyncio' と 'aiofiles' を用いた非同期処理への移行を検討
def write_large_file_sync(data):
    with open("large_file.dat", "wb") as f:
        f.write(data)

5.3. TEMP / TEMPORARY: 一時的な実装

意味: HACK ほどネガティブではなく、デバッグ目的のログや、リリース前に削除すべきスタブ（仮実装）など、中立的な「一時措置」。

使用例:

# TEMP: 機能Bの結合テストが完了するまでの一時的なスタブ
#       2025-12-01までに削除予定
def call_feature_b():
    print("TEMP: feature_b called (stub)")
    return True

---

6. まとめ

本記事で紹介したコメントのアノテーション・タグ（キーワード）を利用することで、「保守性の高い、情報豊富なコード」に近づくことができます。

大事なのは、これらのキーワードの意味をチーム全体で共有し、活用することです。
ぜひ、チームで共有し、開発効率とコード品質の向上に役立ててください。

---