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

はじめに

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

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

ざっと見たい方へ

記法	説明	例
TODO:	将来的に実装や改善が必要な項目を示す。優先度や担当者を含めることも。	// TODO: ユーザー認証をOAuth2.0に移行する
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

既知の問題や不具合がある箇所を示すします。可能であれば問題の詳細や修正の方向性を含めるとgood。

例:

// FIXME: メモリ使用量の最適化が必要
List<int> generateLargeList() {
  // リスト生成の実装
}

NOTE

コードの重要な意図、設計上の決定、または特別な考慮事項を説明する。

例:

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

OPTIMIZE / PERF

パフォーマンスや効率の改善が必要な箇所を示す。具体的な改善案があれば記述。

例:

// OPTIMIZE: このループの効率を改善する
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));
  }