本日はAWESOME-COPILOTの技術調査枠です。
AWESOME-COPILOTのドキュメントを読みながら実際に操作を試して記事に残します。
今回はカスタムインストラクションの一つSelf-explanatory Code Commenting Instructionsについてです。
Self-explanatory Code Commenting Instructions
Self-explanatory Code Commenting Instructionsはコメントを減らし自己説明的（self-explanatory）なコードを書くルールです。
全ファイル・全言語対象 です。
JavaScript例が使われていますが、コメントが存在する言語全般（C#, Rust, TypeScript, Python, Unity/C# など） に効きます。
以下のページからGenaiscriptのインストールボタンをクリックして取得します。
github.com
インストールボタンを押してSelf-explanatory Code Commenting Instructionsをダウンロードします。
すると.github/instructions配下にインストラクションがインストールされます。
インストールしたインストラクションはCopilotの動作に自動的に適用されます。
このインストラクションを読み込むと、Copilotはコード自体を分かりやすくし、必要最小限だけコメントを書くシニアエンジニアとして振る舞います。
具体的にはCopilotは以下のような行動をとります。
コメントを減らしコード自体を説明的にする
本インストラクションの最大の特徴は、「コメントを書く前にコードを改善しようとする」点です。
Copilot はまずコメントが必要なコード = 読みにくいコードと判断する方向になります。
例えば以下のように、変数名・関数名・構造で意味を伝える方向に寄ります。
int retryCount = 0; retryCount++;
string userName = user.Name;
Copilot は以下の考慮を行うようになります。
- 短すぎる変数名を避ける
- 意味のある命名をする
- 小さい関数へ分割する
- self-documenting code を優先する
「WHAT」ではなく「WHY」をコメントする
Copilotは以下のようなコードを読み上げるだけのコメントを避けます。
// 配列をソート items.sort();
以下のような、“なぜそうしているか”を書こうとします。
// APIの表示順と一致させるため作成日時順に並べる items.sort(sortByCreatedAt);
| コメント対象 | Copilotの判断 |
|---|---|
| 処理内容（WHAT） | 不要 |
| 理由（WHY） | 推奨 |
| 制約 | 推奨 |
| 設計意図 | 推奨 |
複雑ロジックだけコメントを書くAIになる
単純な処理にはコメントを付けなくなります。
以下のような「未来の自分が困る場所」だけコメントを残します。
ビジネスロジック
// VIP顧客は離脱防止のため3か月以内なら返金許可
非自明アルゴリズム
# Floyd-Warshall を利用 # 全ノード間距離が必要なため
正規表現
// メールアドレス形式を検証 const emailRegex = ...
API制約
// Quest APIはメインスレッド限定
TODO/FIXMEなどの「意図ある注釈」を使うようになる
Copilotはメンテナンス用annotation commentを積極利用するようになります。
例えば以下のような将来アクション可能なコメントを生成しやすくなります。
C#
// TODO: OpenXR移行後に削除
TypeScript
// FIXME: メモリリークの可能性あり
Rust
// HACK: Meta SDK v74 の不具合回避
Python
# PERF: 高頻度呼び出しのためキャッシュ検討
コメントのアンチパターンを避ける
Copilotは以下を避けるようになります。
不要なコード
// const oldMethod = ...
更新履歴コメント
// User modified this 2025/01/01
区切り罫線
//===================== // Utility Methods //=====================
Public APIのコメント品質が上がる
Copilotは公開APIにはしっかりコメントを書く方向になります。
以下のように、利用者向けドキュメントは厚くなります。
/// Loads LCC data from the specified file. /// /// <param name="path"> /// Absolute path to meta.lcc. /// </param> /// <exception cref="IOException"> /// Thrown when the file cannot be opened. /// </exception> void Load(string path)
内部コード → コメント減少
公開API → コメント増加
という振る舞いになります。
