Belgelendirme

Adlar eşleştiğinde bir bileşenden söz etmek mümkün olur, ama onu kullanmak için yeterli değildir. acilir-liste bileşeninin hangi durumda arama-alani yerine seçileceği, kip-pencere yerine ne zaman ayrı bir sayfa kullanılacağı ve rozet ile bildirim-seridi arasındaki ayrım adlardan okunamaz.

Belgelendirme bu kararları taşır. Bileşen belgesi bir kullanım kılavuzu değil, bileşenin sözleşmesinin okunabilir hâlidir: ne yapar, ne yapmaz, hangi girdileri alır, hangi durumda seçilmez. Bu ders belgenin zorunlu bölümlerini tanımlar ve kapsamın nasıl ölçüleceğini gösterir.

Belgenin Zorunlu Bölümleri

Bileşen belgesinin bölümleri, kullanan kişinin sırayla sorduğu sorulara karşılık gelir:

• Amaç. Bileşen hangi işi görür? Tek cümle. Amacı iki cümleyle anlatılan bir bileşen genellikle iki bileşendir.
• Ne zaman kullanılır. Hangi bağlamda doğru seçimdir. Bu bölüm bileşeni tarif etmez, seçim ölçütü verir.
• Ne zaman kullanılmaz. Karşı örnek. Yerine hangi bileşenin kullanılacağını söyler.
• Özellik tablosu. Girdi özelliklerinin adları, aldıkları değerler, varsayılanları ve zorunlu olup olmadıkları.
• Örnek. Kopyalanıp çalıştırılabilir kullanım. Görsel değil, kaynak metin.
• Erişilebilirlik notu. Klavye davranışı, odak sırası ve bileşenin kendiliğinden sağladığı ile kullananın sağlaması gerekenin ayrımı.
• İlgili bileşenler. Komşu bileşenlere bağlantı; kullanan kişi yanlış yerden başlamış olabilir.

Bu yedi bölümün altısı tanıdıktır. Sistemlerin çoğunda en sık eksik kalan iki bölüm, karşı örnek ile ilgili bileşenlerdir; ikisi de aynı işi yapar: kullanıcıyı bu bileşenden uzaklaştırma işini.

Karşı Örneğin Taşıdığı Bilgi

Örnek, bileşenin doğru kullanımını gösterir. Karşı örnek ise başka bir şey gösterir: bileşenin sınırını. İkisi birbirinin yerine geçmez.

Katalog arayüzünden somut bir örnekle: rozet bileşeni bir kaydın durumunu gösterir — “rafta”, “ödünçte”, “ayırtılmış”. bildirim-seridi ise kullanıcıya bir olay bildirir — “ödünç alma işlemi tamamlandı”. İkisi de küçük, renkli, kısa metinli kutulardır ve ikisi de bir durumu anlatır. Ayrımı yalnızca karşı örnek yazılı hâle getirir: rozet bir nesnenin özelliğidir ve nesneyle birlikte durur; bildirim şeridi bir eylemin sonucudur ve eylemden sonra belirir. Bu ayrım özellik tablosundan okunamaz, çünkü iki bileşenin özellikleri neredeyse aynıdır.

Karşı örneğin ikinci işi, kaçış deliğinin kapatılmasıdır. Bileşen Tabanlı Arayüz Geliştirme kursunda gösterildiği gibi bir bileşen çağırana kaçış deliği verir; belge, bu deliğin nerede biteceğini söylemezse her ekip kendi sınırını çizer. “Rozet içine düğme koymayın, tıklanabilir durum için dugme bileşenini kullanın” cümlesi bir kuraldır ve denetlenebilir.

Kapsamın Hesaplanması

Belgelendirmenin “yapıldı” ya da “yapılmadı” olarak izlenmesi işe yaramaz; belgeler kısmen yazılır ve kısmen eskir. Aşağıdaki program kataloğun on dokuz belgelenmiş bileşenini alır, bölüm bazında ve bileşen bazında kapsamı hesaplar, eksikleri kullanım etkisine göre sıralar ve son olarak özellik tablosunu gerçek arayüzle karşılaştırır.

// belge.mjs — belgelendirme kapsaminin bilesen ve bolum duzeyinde hesabi

// Bir bilesen belgesinin zorunlu bolumleri.
const BOLUM = ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"];

// Her bilesen icin var olan bolumler ve kullanim sayisi (01. dersteki katalogla ayni).
const BELGE = [
  { ad: "dugme",           kullanim: 412, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "baglanti",        kullanim: 268, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "rozet",           kullanim: 188, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu"] },
  { ad: "kart",            kullanim: 157, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "metin-alani",     kullanim: 143, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "onay-kutusu",     kullanim:  96, var: ["amac", "ne-zaman", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "arama-alani",     kullanim:  71, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "bildirim-seridi", kullanim:  63, var: ["amac", "ne-zaman", "ozellik-tablosu", "erisim-notu"] },
  { ad: "acilir-liste",    kullanim:  57, var: ["ozellik-tablosu", "ornek"] },
  { ad: "bos-durum",       kullanim:  52, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "kip-pencere",     kullanim:  45, var: ["amac", "ne-zaman", "ozellik-tablosu", "erisim-notu"] },
  { ad: "sayfalama",       kullanim:  41, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "iskelet",         kullanim:  38, var: ["amac", "ne-zaman", "ozellik-tablosu", "ornek"] },
  { ad: "radyo-grubu",     kullanim:  34, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "ilgili"] },
  { ad: "kirinti-yolu",    kullanim:  29, var: ["amac", "ne-zaman", "ne-zaman-degil", "ozellik-tablosu", "ornek", "erisim-notu", "ilgili"] },
  { ad: "sekmeler",        kullanim:  24, var: ["amac", "ne-zaman", "ozellik-tablosu", "ornek"] },
  { ad: "akordeon",        kullanim:  17, var: ["amac", "ozellik-tablosu", "ornek"] },
  { ad: "arac-ipucu",      kullanim:  12, var: ["ozellik-tablosu"] },
  { ad: "tablo",           kullanim:   9, var: ["ozellik-tablosu", "ornek"] },
];

// Bolum bazli kapsam: hangi bolum en cok eksik?
console.log("bölüm             belgesi olan   bileşen payı   kullanım payı");
const toplamKullanim = BELGE.reduce((t, b) => t + b.kullanim, 0);
for (const bol of BOLUM) {
  const olan = BELGE.filter((b) => b.var.includes(bol));
  const k = olan.reduce((t, b) => t + b.kullanim, 0);
  console.log(
    `${bol.padEnd(17)} ${String(olan.length).padStart(9)}/${BELGE.length} ` +
    `${((olan.length / BELGE.length) * 100).toFixed(1).padStart(12)}% ` +
    `${((k / toplamKullanim) * 100).toFixed(1).padStart(13)}%`
  );
}

// Bilesen bazli kapsam ve eksik etkisi.
const satirlar = BELGE.map((b) => {
  const eksik = BOLUM.filter((bol) => !b.var.includes(bol));
  return { ...b, eksik, kapsam: (BOLUM.length - eksik.length) / BOLUM.length, etki: eksik.length * b.kullanim };
}).sort((a, b) => b.etki - a.etki);

console.log("\nbileşen           kapsam   kullanım   eksik etkisi   eksik bölümler");
for (const s of satirlar) {
  if (s.eksik.length === 0) continue;
  console.log(
    `${s.ad.padEnd(17)} ${(s.kapsam * 100).toFixed(0).padStart(5)}% ${String(s.kullanim).padStart(10)} ` +
    `${String(s.etki).padStart(14)}   ${s.eksik.join(", ")}`
  );
}

const hamKapsam = satirlar.reduce((t, s) => t + s.kapsam, 0) / satirlar.length;
const agirlikliKapsam = satirlar.reduce((t, s) => t + s.kapsam * s.kullanim, 0) / toplamKullanim;
console.log(`\nham kapsam (bileşen ortalaması) : %${(hamKapsam * 100).toFixed(1)}`);
console.log(`kullanımla ağırlıklı kapsam     : %${(agirlikliKapsam * 100).toFixed(1)}`);

// Ozellik tablosunun gercek arayuzle karsilastirilmasi.
const ARAYUZ = {
  dugme:        ["tur", "boyut", "durum", "simge", "genislik"],
  "acilir-liste": ["boyut", "durum", "aramali", "coklu"],
  rozet:        ["ton", "boyut"],
  "kip-pencere": ["boyut", "kapatilabilir", "baslik"],
};
const BELGELENEN = {
  dugme:        ["tur", "boyut", "durum", "simge"],
  "acilir-liste": ["boyut", "durum"],
  rozet:        ["ton", "boyut", "ikonlu"],
  "kip-pencere": ["boyut", "baslik"],
};

console.log("\nözellik tablosu sapması");
console.log("bileşen           belgelenmemiş        belgede olup arayüzde olmayan");
for (const ad of Object.keys(ARAYUZ)) {
  const eksik = ARAYUZ[ad].filter((o) => !BELGELENEN[ad].includes(o));
  const fazla = BELGELENEN[ad].filter((o) => !ARAYUZ[ad].includes(o));
  console.log(`${ad.padEnd(17)} ${JSON.stringify(eksik).padEnd(20)} ${JSON.stringify(fazla)}`);
}
const toplamOzellik = Object.values(ARAYUZ).reduce((t, a) => t + a.length, 0);
const belgelenen = Object.keys(ARAYUZ).reduce((t, ad) => t + ARAYUZ[ad].filter((o) => BELGELENEN[ad].includes(o)).length, 0);
console.log(`özellik tablosu kapsamı: ${belgelenen}/${toplamOzellik} (%${((belgelenen / toplamOzellik) * 100).toFixed(1)})`);

bölüm             belgesi olan   bileşen payı   kullanım payı
amac                     16/19         84.2%          95.6%
ne-zaman                 15/19         78.9%          94.6%
ne-zaman-degil           10/19         52.6%          79.4%
ozellik-tablosu          19/19        100.0%         100.0%
ornek                    16/19         84.2%          93.2%
erisim-notu              12/19         63.2%          89.1%
ilgili                   10/19         52.6%          74.2%

bileşen           kapsam   kullanım   eksik etkisi   eksik bölümler
acilir-liste         29%         57            285   amac, ne-zaman, ne-zaman-degil, erisim-notu, ilgili
bildirim-seridi      57%         63            189   ne-zaman-degil, ornek, ilgili
rozet                86%        188            188   ilgili
kip-pencere          57%         45            135   ne-zaman-degil, ornek, ilgili
iskelet              57%         38            114   ne-zaman-degil, erisim-notu, ilgili
onay-kutusu          86%         96             96   ne-zaman-degil
sekmeler             57%         24             72   ne-zaman-degil, erisim-notu, ilgili
arac-ipucu           14%         12             72   amac, ne-zaman, ne-zaman-degil, ornek, erisim-notu, ilgili
akordeon             43%         17             68   ne-zaman, ne-zaman-degil, erisim-notu, ilgili
tablo                29%          9             45   amac, ne-zaman, ne-zaman-degil, erisim-notu, ilgili
radyo-grubu          86%         34             34   erisim-notu

ham kapsam (bileşen ortalaması) : %73.7
kullanımla ağırlıklı kapsam     : %89.4

özellik tablosu sapması
bileşen           belgelenmemiş        belgede olup arayüzde olmayan
dugme             ["genislik"]         []
acilir-liste      ["aramali","coklu"]  []
rozet             []                   ["ikonlu"]
kip-pencere       ["kapatilabilir"]    []
özellik tablosu kapsamı: 10/14 (%71.4)

Bölüm Bazlı Kapsamın Söylediği

İlk tablo, hangi bölümün sistem genelinde eksik kaldığını gösteriyor. Özellik tablosu yüzde yüz doludur; çünkü arayüzden üretilebilir ve genellikle üretilir. Karşı örnek ile ilgili bileşenler ise yüzde 52,6’da kalıyor: her iki bileşenden yalnızca biri bu bölümlere sahip.

Bu dağılım rastgele değildir. Otomatik üretilebilen bölüm dolu, karar yazmayı gerektiren bölüm boş. Belgelendirme eksiği çoğu zaman zaman eksikliği değil, karar eksikliğidir: karşı örnek yazmak için bileşenin sınırının kararlaştırılmış olması gerekir ve o karar verilmemiştir.

İki sütun arasındaki fark da anlamlıdır. Karşı örnek bileşenlerin yüzde 52,6’sında var ama kullanımın yüzde 79,4’ünü kapsıyor; yani eksik olanlar çoğunlukla az kullanılan bileşenler. İlgili bileşenler bölümünde ise fark daha dar: yüzde 52,6’ya karşı yüzde 74,2. Bu, eksikliğin çok kullanılan bileşenlere de sıçradığını gösterir ve ikinci tablo bunu doğruluyor.

Eksiğin Sıralanması

İkinci tablo, kapsam yüzdesiyle iş önceliğinin aynı şey olmadığını gösteriyor. rozet yüzde 86 kapsamla listedeki en iyi durumdaki bileşenlerden biri, ama eksik etkisi 188 ile üçüncü sırada; çünkü 188 yerde kullanılıyor ve tek eksiği herkesi etkiliyor. tablo ise yüzde 29 kapsamla çok daha kötü durumda ama etkisi 45; dokuz yerde kullanılıyor.

Eksik etkisi çarpımı — eksik bölüm sayısı ile kullanım sayısının çarpımı — bu iki bilgiyi tek sıralamada birleştirir. Sıralamanın başındaki acilir-liste, önceki derste de görülmüştü: belgesiz bir aday olmasına karşın 57 yerde kullanılıyor. İki ayrı denetim aynı bileşeni işaret ettiğinde, o bileşen sıradaki iştir.

Ham kapsam ile ağırlıklı kapsam arasındaki 15,7 puanlık fark da okunmalıdır. İki sayı farklı sorulara yanıt verir: ham kapsam “kataloğun ne kadarı belgelendi”, ağırlıklı kapsam “kullanımın ne kadarı belgeli bir bileşene düşüyor” sorusuna. Yalnız ağırlıklı sayıyı raporlamak, az kullanılan bileşenlerin sürekli belgesiz kalmasını gizler; yalnız ham sayıyı raporlamak ise rozet gibi tek eksikli ama yaygın bileşenleri gözden kaçırır. İkisi birlikte raporlanır.

Özellik Tablosunun Eskimesi

Son blok belgenin en sinsi çürüme biçimini gösteriyor: belge var, ama yanlış. dugme bileşeninin genislik özelliği ve acilir-liste bileşeninin iki özelliği arayüze eklenmiş ama tabloya yazılmamış. Bunlar eksik bilgidir; kullanan kişi özelliğin varlığını bilmez, kendi çözümünü yazar ve sapma üretir.

rozet satırı ise farklı bir kusur taşıyor: ikonlu özelliği belgede duruyor, arayüzde yok. Bu yanlış bilgidir ve eksikten daha pahalıdır; kullanan kişi belgeye güvenip özelliği verir, hiçbir şey olmaz, hatanın nedenini kendi kodunda arar.

Bu blok aynı zamanda çözümün yönünü gösterir. Özellik tablosu elle yazıldığı sürece eskimesi kaçınılmazdır; arayüz tanımından üretildiğinde ise sapma yapısal olarak imkânsız hâle gelir. Elle yazılması gereken bölümler — amaç, seçim ölçütü, karşı örnek — zaten üretilemeyen bölümlerdir. Belgelendirme aracının seçimi bu ayrıma göre yapılır: üretilebilir olanı üreten, üretilemeyeni yazmaya zorlayan bir düzen.

Özet

• Bileşen belgesi yedi bölümden oluşur ve her bölüm kullanan kişinin sorduğu belirli bir soruya karşılık gelir.
• Karşı örnek, özellik tablosundan okunamayan sınır bilgisini taşır; benzer görünen iki bileşen arasındaki ayrımı yazılı hâle getiren tek bölüm odur.
• Otomatik üretilebilen bölümler dolu, karar yazmayı gerektiren bölümler boş kalır; belgelendirme eksiği çoğu zaman karar eksikliğidir.
• Kapsam ham ve kullanımla ağırlıklı olarak birlikte raporlanır; biri az kullanılan bileşenlerin ihmalini, diğeri yaygın bileşenlerdeki tek eksiği gizler.
• Eksik bölüm sayısı ile kullanımın çarpımı, kapsam yüzdesinden farklı bir iş sıralaması üretir.
• Belgede olup arayüzde olmayan bir özellik, arayüzde olup belgede olmayandan pahalıdır; özellik tablosu arayüz tanımından üretildiğinde bu sapma yapısal olarak ortadan kalkar.

Sonraki Adım

Belgedeki özellik tablosunun arayüzle karşılaştırılması bir soruyu açıkta bıraktı: dugme bileşenine genislik özelliğinin eklenmesi ile rozet bileşeninden ikonlu özelliğinin kaldırılması aynı ağırlıkta değildir. Birincisi hiçbir kullanımı bozmaz, ikincisi o özelliği veren her yeri bozar. Sonraki ders bu ayrımı sürüm numarasına bağlar: iki sürümün bileşen arayüzlerini karşılaştıran, değişiklikleri sınıflandıran ve sonraki sürüm numarasını hesaplayan bir betik yazar, buradan göç kılavuzunu üretir.