小説家というと、「比喩」の考案に命を削る...というようなイメージがあります（古いかな？）が、プログラムでもコメントを付ける時には、「適切な比喩」をしたいよね...とは思います。

え、プログラミングで「比喩」って？

はい、それはデザインパターンです。

デザインパターンは元々、

頻繁に使われる解決策に名前をつけて、それらを『プログラマ同士の間』でもコミュニケーションの手段として役立つようにしよう！

という意図もあってああいうカタログができたわけです。言い換えると「知ってる」だけじゃ意味がなく、使って、しかも「使ってる」ことを言葉で名指すことが、「デザインパターンを使う」ことなのです。ですから、プログラムでパターンを使っていたら、これはぜひぜひソースの先頭にでもパターン名とそのクラスの役割名を書いておくべきです。

あるいは、

/** Factory Method */
public abstract MyInterface getMyInterface();

のように、パターンで特徴的なメソッドにその旨を書いておき、「これを上書きして適切な継承クラスを返すサブクラスを作るんだよ！」というあたりを明示すべきでしょう。この時、いちいち説明を書くよりも、ただ一言「Factory Method」の方が断然優れています。「饒舌で詳細な記述よりも、適切な比喩」というあたりでしょうか？ 比喩の元は、プログラムのような抽象構造の場合には、デザインパターンそのものなのです。

で...これを少し発展させると、こういう考え方もできます。

@Immutable
public final class ImmutableClass {
.....
}

このクラスは Immutable なものとします。その時、アノテーションをコメントと兼用して、「このクラスは Immutable である」ことを伝えると同時に、この @Immutable アノテーションを処理して、「このクラスが本当に Immutable の制約条件にしたがっているか」をチェックする、というのはアリでしょう。 Immutable の場合は、ざっとこれくらいが制約条件になります。

1. 1. final クラスである（望ましい）
2. 2. フィールドはすべて final 修飾がなされている（望ましい）。
3. 3. セッタは存在せず、すべてコンストラクタ引数で値がセットされる。
4. 4. List などの「集合」を返すメソッドではコピーしたものを返す。

このような形式的条件だったら、ある程度自動的にチェックすることも可能です。でしたら、アノテーションプロセッサを自分で作ってしまうのもアリでしょう。

「プログラマに向けられた注釈」と「自動チェック可能な制約」とを同時に兼ねるようなコメントのあり方....というのは実はかなり強力な武器になる可能性があります。実際、こういう「プログラマ向けの注釈＆その内容を検証する自動処理」のコンセプトをEiffel のような「契約によるプログラミング」言語は備えています。単に「プログラマが読んで役に立つ」から一歩進んで、「それと同時に、そこで書かれた制約条件を、自動的にチェックできる」というのは、なんと面白くしかもパワフルなことでしょう！