code-style

必要に応じて $precise-minor-adjustment スキルを読み込んでください。このスキルは、コードをシンプルにし、コードベース内の他の部分と一貫性を持たせる方法をエージェントに伝えるものです。

作業が終わったら、コミットまたは要約する前に、$precise-minor-adjustment に従って簡素化も一度行ってください。

コードスタイル

必要に応じて、以下の対応するファイルを読んでください。

言語	リファレンス
JavaScript / TypeScript	languages/js-ts.md
Rust	languages/rust.md

私のコードスタイルで最も重要なルールは、不規則なロジックの中にある規則的なパターンを常に見つけることです。コードの整理方法は変更してもかまいません。また、コメントを使ってこの目標を達成することもできます。

整理

コーディングで目指すことの一つは、コードをより構造化し、予測しやすくすることです。そうすれば、人間がコードを扱い、レビューしやすくなります。

たとえば、大きな match（Rust）を使い、ケースごとに異なる分岐をシンプルな行で処理できます。

構造化され、予測しやすい1,000行のコードのほうが、雑然とした500行のコードより優れています。

コメント

複雑なロジックにはコメントが必要です。 リンターやチェッカーで必要とされない限り、コメントの文を複数行に分けないでください。

コメントはシンプルで短く保ってください。次に読む人が3秒でコードから推測できるなら、そのコメントは不要です。

コードだけでは表現できないことを説明するコメントは残してください。

• 自明でない制約や外部要件
• 一見するとより良い方法に思える選択肢を採用しなかった理由
• 仕様、上流サービスの特性、コンプライアンス規則など、コードベースの外部にのみ存在する背景情報

また、コメントでは何をするかではなく、なぜそうするのかを説明してください。

関数名を言い換えただけのドキュメントコメントは書かないでください。何の役にも立たず、いずれ実際の内容と食い違います。

---

複雑な関数では、フローコメントも有効な注釈の一つです。複数の段階に分かれる複雑なロジックには、コードを異なる部分に分けて理解しやすくするため、// 1. Check environment // 2. Read config のようなコメントを追加できます。

ロジックを複数の段階に明確に分けられ、50行を超える場合は、フローコメントが必要です。

---

実装全体が終わったら、コードの差分を確認してください。コメントを追加せずに差分が50行を超えている場合は、問題があります。

可視性

まず何も公開せず、別のモジュールから必要とされる場合にのみ公開してください。

すべてのエクスポートや公開項目は契約であり、安定性を保ち、互換性を維持する必要がある名前です。公開範囲はできる限り小さくしてください。

診断への対応

私のプロジェクトには厳格なリンティングルールが設定されています。診断に遭遇するのは普通のことです。

診断に遭遇したら、まずコードを変更するのではなく、考えてください。その診断の目的が、現在のコードの目的や目標とする動作に合っているか確認してください。また、その診断に従うことで、コードがより複雑になるのか、分かりにくくなるのか、シンプルになるのかも確認してください。

不合理な診断は退け、妥当な診断には従ってください。コードスタイルに沿ってください。

不合理な診断を退ける場合は、設定ファイルを変更したりルールを全体で無効にしたりするのではなく、コメント（// oxlint-disable-...、#[allow(...)]）を使って無効にする方法を優先してください。同じルールを無効にしている例がほかにないか、コードベースを確認してもかまいません。同じルールが何度も無効にされている場合は、回答で設定ファイルの調整を提案できます。ただし、指示がない限り自分で変更しないでください。

作業後

目標を達成したら、自分でコードをレビューしてください。特にコードの整理に注意してください。