決めたことを残す12 / 20
意図カバレッジを見る
このページの内容
このソフトウェアを、どこまで把握できていますか。意図カバレッジは、一枚の図で答えます。コードファイルごとに一マス、モジュールごとに並び、マスが濃いほど、説明に引用されている行が多いことを示します。まだ空白のところも、説明が古くなったところも、一目で分かります。意図を指すと、その意図が及ぶファイルが光ります。
意図カバレッジを開く
新しいチャットを始めます。最初のメッセージを送る前は、チャット欄に意図カバレッジのカードが表示されます。設定 → 意図カバレッジ（現在のプロジェクトのグループ内）を開くこともできます。カードがページいっぱいに表示されるので、大きなプロジェクトで役立ちます。
意図カバレッジには、実装フォルダが Git リポジトリであることが必要です。プロジェクトにカバレッジの結果がまだないうちは、カードに「まだ計算されていません」と表示され、二つの入り口があります。「説明」は、先に Agent に説明を書かせます。「今すぐ計算」は、すでにある説明からカバレッジを計算します。大きなリポジトリではすべてのファイルを読むので、時間がかかることがあります。
それ以降は、説明が終わるたびにカードが更新されます。タイトル行の右には、直近の説明が終わった時刻とそのときのコミットが表示され、再計算のボタンがあります。
カードを読む
カードの上部には大きな数字があります。範囲内のすべてのコード行のうち、説明に引用されている割合です。その横の「3 / 6 ファイル」は、全体のうち、意図の裏付けがあるファイルの数です。
その下のバーは三つの部分でできていて、下に凡例があります。
- 参照されている行：塗りつぶされた部分。パーセンテージと同じ長さです。
- 説明が古い：斜線の部分。説明が書かれたあとに変更されたファイルです。
- 意図なし：空の部分。どの説明にも引用されていないファイルです。
モジュール別
「モジュール」の領域は、既定では点で表示されます。ファイルごとに一つの点、フォルダごとに一行です。意図の裏付けがあるファイルは、引用されている行が多いほど濃くなります。説明が古いファイルは斜線で、意図のないファイルは空で表示されます。点にポインターを合わせると、ファイル名と、どれだけ引用されているかが見られます。
右上のスイッチで、点をバーに切り替えられます。モジュールごとに一行で、行数に応じた長さになり、三つの状態に分けられます。
モジュールをクリックすると、一階層下に進みます。戻るボタンとパスがタイトル行に現れます。たとえばこのサブスクリプションサービスでは、billing、jobs、notify、web の行が並び、notify の行はほとんど空です。通知メールのルールが、まだ意図に書かれていないのです。
意図別
モジュールの下には意図の一覧があり、意図ドキュメントごとに一行で、ドキュメントツリーのようにインデントされ、いくつのファイルに対応するかを示す短い線が付きます。まだ裏付けとなるコードがないドキュメントは、灰色で、線も空です。
- ドキュメントにポインターを合わせると、モジュール領域のうち、それと関係のない行が薄くなります。レイアウトは動きません。
- ドキュメントをクリックすると、関係のない行がたたまれ、バーと点にはその意図が対応するコードだけが表示されます。モジュールの見出しの下には、ドキュメント名と × の付いたチップが現れます。
- もう一度クリックするか、チップの × をクリックするか、
Escを押すと解除されます。
たとえば更新をクリックすると、billing/grace.ts、jobs/renewal-job.ts、いくつかのテストファイルだけが残ります。更新のルールを変えたら何に触れるかが、すぐに分かります。
数字の意味
カバレッジが測るのは、説明がどれだけのコードを引用しているかです。コードの品質ではなく、テストカバレッジでもありません。二つの問いに答える助けになります。
- まだ意図がないのはどこか。空白のモジュールは、あまり重要でないコードか、すでに動いているのに考え抜いていないルールのどちらかです。後者には、意図を一段落書いて、説明を実行する価値があります。
- 説明が古いのはどこか。斜線が多いのは、説明が追いついていない最近の変更があるということです。コードが変わったときをご覧ください。
100%を追いかける必要はありません。いちばん大切なところから始めて、そこから先に濃くしていきましょう。
Parnas Index
設定 → Parnas Index は、同じことを反対側から見ます。コードの変更が、意図のどこまで及ぶかです。名前は、David Parnas のモジュール分割の原則に由来します。よいモジュールは、変わりやすい決定を隠す、という原則です。Noea では、意図の一節が決定を表し、コードファイルがモジュールを表します。
上部の大きな数字は、変更されたファイル一つあたり、平均でいくつの意図の節が再確認されるかです。完全に確認された数と、そのうち変化がなかった数も付きます。数字が高いほど、一つの変更が多くの決定を巻き込みます。期間は7日、30日、90日から選べます。
ページには二つの表示があります。
| 表示 | 階層 | 列 |
|---|---|---|
| このコードが影響する意図 | ファイル、定義 | 影響する意図、変更、変更あたり、変化なし |
| この意図に影響するコード | ドキュメント、節 | 参照ファイル、コード変更、意図の変更、変化なし |
行をクリックすると、その場で開きます。ファイルの行には、説明がどれだけ引用しているか、最も影響する意図、「意図カバレッジで表示」が付きます。意図の行には、引用しているファイルの数、最もそれに影響するコード、その節を開く方法が付きます。
最初の表示のファイル階層の下には、「カバレッジと影響」の散布図があります。横軸は説明に引用されている行の割合、縦軸は変更一つが及ぶ意図の節の数です。右上のファイルは、引用が密で変更も多く、変更のたびに多くの意図を確認し直すことになります。分割を検討する価値があるかもしれません。カバレッジが高いほどよいとは限りません。
プロジェクトに実装フォルダがまだリンクされていなければ、どちらのページも、先に 設定 → プロジェクト でリンクするよう求めます。