🧞

TODO:ばかり使いがちなので、他のアノテーションコメントも調べてみた

2024/08/08に公開

はじめに

コードにコメントを書く方法の一つに、「アノテーションコメント」があります。
アノテーションコメントとは、コードの状態や目的を短く表現したタグのようなコメントのことです。
例えば、よく見かけるTODO:というコメントも、アノテーションコメントの一種です。

「アノテーション」(annotation)という言葉は英語で、日本語では「注釈」や「説明」という意味があります

ざっと見たい方へ

記法	説明	例
`TODO:`	将来的に実装や改善が必要な項目を示す。優先度や担当者を含めることも。	`// // TODO: バリデーションが甘いので、後で強化する (担当: 山田)`
`FIXME:`	既知の問題や不具合がある箇所を示す。可能であれば問題の詳細や修正の方向性を含める。	`// FIXME: 大量データ処理時にメモリリーク発生。`
`NOTE:`	コードの重要な意図、設計上の決定、または特別な考慮事項を説明する。	`// NOTE: この関数は副作用があるため、トランザクション内で使用すること`
`OPTIMIZE:`	パフォーマンスや効率の改善が必要な箇所を示す。具体的な改善案があれば記述。	`// OPTIMIZE: インデックスを追加してクエリ速度を改善する`
`WARNING:`	潜在的なリスクや、使用時に注意が必要な点を警告する。	`// WARNING: このAPIは非推奨。v2.0で削除予定`
`HACK:`	一時的な回避策や、理想的ではない実装を示す。より良い解決策の検討が必要。	`// HACK: ライブラリの制約を回避するため、直接DBアクセスを実装`
`REVIEW:`	特に注意深いコードレビューが必要な箇所を示す。複雑なロジックや重要な変更に使用。	`// REVIEW: 新しい料金計算アルゴリズム。要確認`
`CHANGED:`	コードの重要な変更理由を記述する。変更の影響範囲や背景情報を含めると良い。	`// CHANGED: パフォーマンス向上のため、同期処理から非同期処理に変更`
`XXX:`	動くけどなぜうごくかわからない箇所を示す。	`// XXX: なぜか動くが理由不明。要調査`

✨ 定番のアノテーション

まずは、頻繁に使う（そしてよく見かける）基本のタグから。

TODO:

一番メジャーなやつですね。
「将来的に実装したいこと」や「改善したいこと」をメモします。

例:

// TODO: バリデーションが甘いので、後で強化する (担当: 山田)
void processUserInput(String input) {
  // ...
}

FIXME:

「Fix Me（私を直して）」の名の通り、既知のバグや不具合がある場所に使います。
TODO よりも緊急度が高く、「壊れている」状態を示します。
可能であれば問題の詳細や修正の方向性を含めるとgood。

例:

// FIXME: 空の配列を渡すとクラッシュするバグがある
void calculateAverage(List<int> numbers) {
  ...
}

NOTE:

コードのロジックだけでは伝わりにくい「背景」や「意図」を説明します。
「なんでこんな書き方したの？」と未来の自分にツッコまれないように、理由を残しておきましょう。

例:

/// NOTE: このキャッシュは最大1000アイテムに制限しています。
/// メモリ使用量とルックアップ速度のバランスを取るための設計決定です。
class LimitedCache<K, V> {
  final int _maxSize = 1000;
  final Map<K, V> _cache = {};
    // メソッドの実装
}

🚀 知ってると便利なアノテーション

ここからは、使いこなせると「おっ、こいつできるな」と思われる（かもしれない）アノテーションたちです。

OPTIMIZE / PERF:

動いてはいるけど、パフォーマンスや効率に問題がある場所に使います。
具体的な改善案があれば記述。

例:

// OPTIMIZE: 二重ループになっちゃってるので、あとでMapを使って計算量を減らしたい
void processItems(List<Item> items) {
  // 処理ループの実装
}

WARNING: / WARN:

「さわるな危険」です。
このコードを使うときや変更するときに、注意すべきことがある場合に警告します。
「ここを変えると全体が爆発します」みたいな地雷原には、必ず看板を立てておきましょう。

例:

// WARNING: このメソッドは非推奨APIを使用しているため、早急に更新が必要
void legacyMethod() {
  // 古いAPIを使用した実装
}

😅 開発の「裏事情」を伝えるアノテーション

最後は、理想通りにいかなかった現実を伝えるタグたちです。仏の心で読んであげましょう。

HACK:

きれいなコードではないけれど、「ライブラリのバグ回避」や「急な仕様変更」のために、やむを得ず書いたコードに使います。
いわゆる「やっつけ仕事」ですが、理由を書いておけば許してもらえるはず。

例:

// HACK: パフォーマンス問題を回避するための一時的な対策
int quickCalculation(int value) {
  // 最適化されていない計算の実装
}

REVIEW:

特に注意深いコードレビューが必要な箇所を示します。
複雑なロジックや重要な変更に使用しましょう。

例:

/// REVIEW: このウィジェットの状態管理方法を確認する必要あり
class ComplexWidget extends StatefulWidget {
  // ウィジェットの実装
}

CHANGED:

コードを変更した理由を記述します（コードをどのように変更したかではなく）。

例:

/// CHANGED: パフォーマンス改善のため、同期処理から非同期処理に変更
/// (データベースアクセスのボトルネックを解消)
Future<User> getUserById(String id) async {
  // 新しい非同期実装
}

XXX:

一番不気味なタグです。「動くけど、なぜ動くかわからない」「実装に疑問がある」場合に使います。
危険な香りがプンプンするので、見かけたら注意深く調査しましょう。

例:

 Future<void> processUsers() async {
    List<User> users = await getUsers();
      // XXX: なぜこの遅延が必要なのかよくわからないが、
      // これがないとプログラムが早期に終了する
      await Future.delayed(Duration(seconds: 6));
  }