Niyet kapsamınızı görün — Noea Code belgeleri

Bu yazılımın gerçekten ne kadarına hâkimsiniz? Intent coverage tek bir görüntüyle yanıt verir: her kod dosyası için bir kare, modüllere göre dizilmiş; kare ne kadar koyuysa, açıklamalarınız o dosyanın o kadar çok satırına atıf yapar. Hâlâ neyin boş olduğu ve hangi açıklamaların eskidiği bir bakışta görünür. Bir niyete işaret edin, kapsadığı dosyalar aydınlanır.

Intent coverage’ı açın

Yeni bir sohbet başlatın: ilk mesajı göndermeden önce sohbet alanı Intent coverage kartını gösterir. Kartın sayfayı kapladığı Settings → Intent coverage (geçerli projenin grubunda) bölümünü de açabilirsiniz; büyük projelerde işe yarar.

Intent coverage, Implementation klasörünün bir Git deposu olmasını gerektirir. Projenin bir kapsam sonucu olana kadar kart “Not computed yet” der ve iki giriş yolu sunar: “Explain”, Ajan’a önce açıklamaları yazdırır; “Compute now” ise zaten sahip olduğunuz açıklamalardan kapsamı hesaplar. Büyük depolarda her dosyanın okunması gerektiğinden biraz sürebilir.

Sonrasında kart, Explain her bittiğinde güncellenir. Başlık satırının sağı, son Explain’in ne zaman bittiğini ve o andaki commit’i gösterir; yeniden hesaplamak için bir düğme de vardır.

Kartı okuyun

Kartın üstünde büyük bir sayı vardır: kapsamdaki tüm kod satırlarının, açıklamaların atıf yaptığı payı. Yanındaki “3 / 6 files”, toplam içinde kaç dosyanın arkasında niyet olduğunu gösterir.

Intent coverage kartı: kod satırlarının %68’i açıklamalarca atıf alıyor ve 60 dosyanın 41’inin arkasında niyet var. Modüller alanı her dosya için bir noktayı klasöre göre dizer; her niyet belgesi altında listelenir.

Altındaki çubuğun üç parçası vardır; altında bir gösterge bulunur:

Referenced lines: yüzde kadar uzunlukta dolu kısım.
Explanation outdated: taralı kısım; açıklamaları yazıldıktan sonra değişen dosyalar.
No intent: boş kısım; hiçbir açıklamanın atıf yapmadığı dosyalar.

Modüle göre

“Modules” alanı varsayılan olarak noktaları gösterir: dosya başına bir nokta, klasör başına bir satır. Arkasında niyet olan dosyalar, satırlarının daha çoğu atıf aldıkça koyulaşır; açıklamaları eskimiş dosyalar taralıdır; niyeti olmayan dosyalar boştur. Dosya adını ve ne kadarının atıf aldığını görmek için bir noktaya işaret edin.

Sağ üstteki anahtar noktaları çubuklara çevirir: modül başına bir satır, satır sayısı kadar uzunlukta ve üç duruma bölünmüş.

Bir seviye aşağı inmek için bir modüle tıklayın; başlık satırında bir geri düğmesi ve yol belirir. Örneğin abonelik hizmetinde billing, jobs, notify ve web satırları yan yana durur ve notify satırı neredeyse boştur: bildirim e-postalarının kuralları henüz niyete yazılmamıştır.

Niyete göre

Modüllerin altında niyetlerin listesi vardır: her niyet belgesi için bir satır, belge ağacı gibi girintili, kaç dosyaya eşlendiğini gösteren kısa bir çizgiyle. Arkasında henüz kod olmayan bir belge gri ve boş bir çizgiyle gösterilir.

Bir belgeye işaret edin: modüller alanında onunla ilgisi olmayan satırlar solar, yerleşim yerinde kalır.
Bir belgeye tıklayın: ilgisiz satırlar katlanır, çubuk ve noktalar yalnızca bu niyetin eşlendiği kodu gösterir ve modüller başlığının altında belgenin adı ve bir × içeren bir çip belirir.
Temizlemek için yeniden tıklayın, çipin ×’ine tıklayın ya da Esc tuşuna basın.

Örneğin Yenileme’ye tıklayın; yalnızca billing/grace.ts, jobs/renewal-job.ts ve birkaç test dosyası kalır. Yenileme kurallarında yapacağınız bir değişikliğin nelere dokunacağını hemen görürsünüz.

Sayı ne anlama gelir

Kapsam, açıklamalarınızın ne kadar koda atıf yaptığını ölçer. Kod kalitesi değildir ve test kapsamı da değildir. İki soruyu yanıtlamanıza yardım eder:

Nerede henüz niyet yok? Boş bir modül ya çok önemli olmayan koddur ya da zaten çalışan, ama üzerinde düşünmediğiniz kurallardır. İkincisi, bir paragraf niyeti ve bir Explain’i hak eder.
Nerelerde açıklamalar eskimiş? Yoğun tarama, açıklamaların yetişemediği yakın zamandaki değişiklikler anlamına gelir; bkz. Kod değiştiğinde.

%100’ün peşinden koşmaya gerek yok. En çok önem verdiğiniz kısımlarla başlayın ve önce onların koyulaşmasına izin verin.

Parnas Index

Settings → Parnas Index aynı şeye öbür taraftan bakar: kod değişikliklerinin niyetinize ne kadar uzandığına. Ad, David Parnas’ın modül ayrıştırma ilkesinden gelir: iyi bir modül, değişmesi olası bir kararı gizler. Noea’da bir niyet pasajı bir kararı, bir kod dosyası da bir modülü temsil eder.

Üstteki büyük sayı, değişen dosya başına ortalama kaç niyet pasajının yeniden kontrol edildiğidir; kaçının tam kontrol edildiği ve bunlardan kaçının değişmediği de gösterilir. Ne kadar yüksekse tek bir değişiklik o kadar çok kararı içine çeker. Zaman aralığı 7, 30 ya da 90 gün olabilir.

Sayfanın iki görünümü vardır:

Görünüm	Düzeyler	Sütunlar
Code → intents	Files, Definitions	Intents reached, Changes, Per change, No change
Intents ← code	Documents, Passages	Files cited, Code changes, Intent changes, No change

Bir satırı yerinde açmak için ona tıklayın. Bir dosya satırı, açıklamaların ne kadarına atıf yaptığını, en çok ulaştığı niyetleri ve “View in Intent coverage”ı gösterir; bir niyet satırı kaç dosyaya atıf yaptığını, ona en çok ulaşan kodu ve o pasajı açmanın bir yolunu gösterir.

İlk görünümün dosya düzeyinin altında bir “Coverage and reach” dağılım grafiği vardır: yatay eksen açıklamaların atıf yaptığı satırların payı, dikey eksen her değişikliğin kaç niyet pasajına ulaştığı. Sağ üstteki dosyalar yoğun biçimde atıf alır ve sık değişir; bu yüzden her değişiklik çok sayıda niyetin yeniden kontrol edilmesi anlamına gelir. Bölünmeye değer olabilirler. Daha yüksek kapsam her zaman daha iyi değildir.

Projeye henüz bir Implementation klasörü bağlanmamışsa iki sayfa da önce Settings → Project içinde bir tane bağlamanızı ister.