Belgelendirme İncelemesi

Önceki üç ders üç ekseni ölçtü ve üçünün de nesnesi koddu: imza, gövde, test. Dördüncü eksenin nesnesi kodun dışındadır. Değişiklik bir davranışı değiştirdiğinde o davranışı anlatan metin de değişmelidir; değişmezse geriye, kodun söylediğiyle çelişen bir metin kalır.

Bu ders o ekseni ölçer ve ölçümü bir adım genişletir: beş eksen tek tek kapatılır ve her kapanışın kaybı yan yana konur. Ardından belge ekseninin kendine özgü sınırı ölçülür — yazılmış bir belgenin yanlış olması ile bir davranışın hiç yazılmamış olması arasındaki fark.

Değişikliğin Belgeye Yansıması

Belge ekseninin baktığı metin türleri ayrıdır ve hepsi aynı değişiklikte bulunmaz. Gövdenin yanındaki açıklama satırları, genel arayüzün referans metni, deponun tanıtım dosyası ve kurulum yönergesi, örnek kod parçaları — her biri bir davranışa dayanır ve o davranış değiştiğinde geçersiz olur.

Doküman türlerinin ayrımı, okur tanımı ve yazım disiplini Teknik Yazarlık ve Dokümantasyon kursunun konusudur ve burada tekrarlanmıyor. Bu dersin ölçtüğü tek şey incelemede belgeye bakılıp bakılmadığı ve bakılmadığında ne kaçtığıdır.

Belge ekseninin ayırt edici yanı, bulgusunun bir çelişkiyle bulunmasıdır. Öteki eksenler tek bir metne bakar: arayüz imzaya, gerçekleştirim gövdeye, test iddiaya. Belge ekseni iki metni karşılaştırır — kodun yaptığı iş ile metnin anlattığı iş. Bu yüzden belge kusuru yalnız belge dosyasına bakarak bulunamaz; belgeyi doğru okumak, kodu da okumuş olmayı gerektirir.

Bu karşılaştırma zorunluluğu belge eksenini pahalı gösterir, oysa ucuzlatılabilir. Kodun yaptığı iş zaten arayüz ve gerçekleştirim eksenlerinde okunmuştur; belge ekseni o okumanın üstüne ikinci metni koyar. İki ekseni aynı okumada birlikte taşımak, üçüncü derste ölçülen toplanabilirliğin pratik karşılığıdır — eksenler birbirinin payını yemez ve bir arada yürütülebilir.

Belge Ekseninin Üç Bulgusu

Eskimiş metin. Davranış değişmiş, onu anlatan cümle değişmemiştir. Metin dilbilgisi olarak kusursuzdur ve bir zamanlar doğruydu; bugün yanlıştır. Bu, üçü içinde en sık kaçanıdır, çünkü metnin kendisi değişikliğin içinde görünmez — değişmediği için değişiklikte yer almaz.

Eksik metin. Değişiklik yeni bir genel ad ya da yeni bir yapılandırma seçeneği getirmiş, ama onu anlatan bir metin eklenmemiştir. Bu bulgunun izi değişikliğin içindedir: eklenen ad görünür, karşılığında eklenen bir açıklama görünmez.

Çelişen metin. Aynı davranış iki ayrı yerde anlatılmış ve biri güncellenmiştir. Okur hangisine bakarsa ona inanır; iki metnin çeliştiğini yalnız ikisini birden okuyan görür.

# ogretilen inceleme notu ornegi , calistirilmamistir

eskimis     Islevin aciklama satiri "bos liste doner" diyor; govde artik
            bos deger donduruyor. Aciklamanin yeni davranisa gore
            guncellenmesi gerekiyor.

eksik       Yeni yapilandirma secenegi eklenmis, kurulum yonergesinde
            karsiligi yok. Secenegin varsayilan degeriyle birlikte
            yonergeye eklenmesi gerekiyor.

celisen     Tanitim dosyasindaki ornek eski cagri bicimini kullaniyor,
            referans metni yeni bicimi anlatiyor. Iki metinden biri
            otekine gore guncellenmeli.

Bu blok bir örnektir ve çalıştırılmaz; dersin sayıları yalnız ölçüm bloğundan gelir.

Belge Ekseni Neden Kapanır

Beş eksen içinde en sık kapananı belgedir. Nedenleri kurgunun dışındadır ama tablonun nasıl okunacağını değiştirir.

Belge en sona bırakılır. Değişikliğin gövdesi ve testleri hazırdır, belge “birleştirmeden sonra” yazılacaktır. İnceleme bu durumda ekseni kapatmış olmaz, ertelemiş olur; ölçüm açısından ikisi aynıdır, çünkü o turda belge kusuru bulunmaz.

Belge bulgusu engelleyici sayılmaz. Bir gerçekleştirim bulgusu birleştirmeyi durdurur, bir belge bulgusu çoğu zaman durdurmaz: bulgu yazılır ve değişiklik yine de birleşir. Tablo bu ayrımı içermez — bulunan kusur bulunmuştur, kapanıp kapanmadığı sonraki konuların değişkenidir.

Belge değişikliğin kapsamı dışında durur. Gövdenin yanındaki açıklama satırı değişikliğin içindedir; tanıtım dosyası, kurulum yönergesi ya da referans metni başka bir yerde, hatta başka bir depoda olabilir. Kapsam dışındaki metin incelemeye hiç gelmez ve eksen açık olsa da bulgu üretilemez.

Üçü de yönetilebilir kararlardır ve tablonun verdiği sayı bu kararların fiyatıdır: belge ekseninin kapanması, o turda 3 kusurun kaçması demektir. Kullanışlı olan sayının büyüklüğü değil, kaçanların hangi sınıfta olduğunun önceden bilinmesidir.

Ölçümün Varsayımları

• IE31 — Ortak kurgu değişmez: 600 satır, 12 öbek, 24 kusur, dikkat 12 öbek. Okunmamış öbek yoktur; kaçan her kusurun nedeni bakılmayan eksendir.
• IE32 — Birinci bölümde her satır tek bir inceleyenin okumasıdır ve satırlar arasındaki tek fark, kapatılan eksendir. İlk satırda hiçbir eksen kapatılmaz.
• IE33 — “Kayıp” sütunu, beş eksen açıkken bulunan sayıdan o satırda bulunanın çıkarılmasıdır.
• IE34 — Kaçanın sınıf dökümü, o satırda bulunamayan kusurların sınıflara göre sayımıdır ve azalan sırada yazılır.
• IE35 — Belge kusuru, değişiklikte yazılmış bir metnin kodla çelişmesidir. Kurgu bu metnin nerede durduğunu değil, hangi öbeğe düştüğünü tutar.
• IE36 — Eksik gereksinim kusuru, hiç yazılmamış olanın kusurudur ve bir öbeğe düşmüş olması onu görünür yapmaz; öbek yalnız kusurun ait olduğu yeri işaretler.
• IE37 — Belge ekseni açıldığında yalnız belge sınıfı bulunur; altıncı sınıf hiçbir eksenin arama listesinde değildir ve bu ölçümde de değişmez.
• IE38 — Çözünürlük kusur düzeyinde 1/24 = 0,042, öbek düzeyinde 1/12 = 0,083.

Ölçüm

"""Belgelendirme incelemesi: bir eksen kapatilinca ne kaciyor.

Bolum 1 - bes eksen tek tek kapatilir; bulunan, kacan ve kacanin sinif dokumu.
Bolum 2 - yazilmis belgenin kusuru ile hic yazilmamis gereksinim ayrimi.
"""
TOHUM = 20260815
EKSENLER = ("arayuz", "gerceklestirim", "test", "belge", "bicim")
YAZILMAYAN = "eksik gereksinim"
SINIFLAR = EKSENLER + (YAZILMAYAN,)
DIKKAT = 12
OBEK = 50


def uretec(tohum):
    d = tohum % 2147483646 + 1

    def r(n):
        nonlocal d
        d = (d * 48271) % 2147483647
        return d % n
    return r


def degisiklik(satir, kusur_sayisi=24, tohum=TOHUM):
    r, kusurlar = uretec(tohum), []
    obek_sayisi = max(1, satir // OBEK)
    for i in range(kusur_sayisi):
        kusurlar.append({"no": i + 1, "sinif": SINIFLAR[r(6)],
                         "obek": r(obek_sayisi)})
    return {"satir": satir, "obek": obek_sayisi, "kusurlar": kusurlar}


def incele(d, eksenler, dikkat=DIKKAT):
    okunan = set(range(min(dikkat, d["obek"])))
    return {k["no"] for k in d["kusurlar"]
            if k["sinif"] in eksenler and k["obek"] in okunan}


TAM = set(EKSENLER)
d = degisiklik(600)

print(f"{'kapatılan eksen':<16s} {'açık':>4s} {'bulunan':>7s} {'kaçan':>5s} "
      f"{'kayıp':>5s} {'kaçanın sınıf dökümü':<36s}")
tam = incele(d, TAM)
for e in ("-",) + EKSENLER:
    acik = TAM if e == "-" else TAM - {e}
    b = incele(d, acik)
    kacan = [k for k in d["kusurlar"] if k["no"] not in b]
    dokum = {}
    for k in kacan:
        dokum[k["sinif"]] = dokum.get(k["sinif"], 0) + 1
    metin = ", ".join(f"{s} {n}" for s, n in
                      sorted(dokum.items(), key=lambda x: -x[1]))
    print(f"{e:<16s} {len(acik):4d} {len(b):7d} {len(kacan):5d} "
          f"{len(tam) - len(b):5d} {metin:<36s}")

print()
belge = [k for k in d["kusurlar"] if k["sinif"] == "belge"]
yazilmayan = [k for k in d["kusurlar"] if k["sinif"] == YAZILMAYAN]
print(f"{'sınıf':<18s} {'kusur':>5s} {'öbek':<12s} {'belge ekseni bulur mu':>21s}")
print(f"{'belge':<18s} {len(belge):5d} "
      f"{str(sorted(k['obek'] for k in belge)):<12s} {'evet':>21s}")
print(f"{YAZILMAYAN:<18s} {len(yazilmayan):5d} "
      f"{str(sorted(k['obek'] for k in yazilmayan)):<12s} {'hayır':>21s}")
for ad, acik in (("belge ekseni açık", TAM), ("belge ekseni kapalı",
                                              TAM - {"belge"})):
    b = incele(d, acik)
    kacan = [k for k in d["kusurlar"] if k["no"] not in b]
    print(f"{ad:<20s} belge kaçan "
          f"{sum(1 for k in kacan if k['sinif'] == 'belge')}, "
          f"yazılmayan kaçan "
          f"{sum(1 for k in kacan if k['sinif'] == YAZILMAYAN)}")

kapatılan eksen  açık bulunan kaçan kayıp kaçanın sınıf dökümü                
-                   5      22     2     0 eksik gereksinim 2                  
arayuz              4      19     5     3 arayuz 3, eksik gereksinim 2        
gerceklestirim      4      16     8     6 gerceklestirim 6, eksik gereksinim 2
test                4      19     5     3 test 3, eksik gereksinim 2          
belge               4      19     5     3 belge 3, eksik gereksinim 2         
bicim               4      15     9     7 bicim 7, eksik gereksinim 2         

sınıf              kusur öbek         belge ekseni bulur mu
belge                  3 [2, 2, 3]                     evet
eksik gereksinim       2 [2, 10]                      hayır
belge ekseni açık    belge kaçan 0, yazılmayan kaçan 2
belge ekseni kapalı  belge kaçan 3, yazılmayan kaçan 2

Beş Eksen Tek Tek Kapatılınca

Üst tablo bu konunun kapanış tablosudur: aynı değişiklik, aynı tek inceleyen, tek fark kapatılan eksen.

Kayıp sütunu beş satırda da tek bir kuralı doğruluyor: 3, 6, 3, 3, 7. Bu sayılar sınıf dağılımının kendisidir. Bir eksen kapatıldığında kaybedilen kusur sayısı, o eksenin sınıfındaki kusur sayısına eşittir — ne eksik ne fazla. Üçüncü dersin sıra bağımsızlığı ölçümü bunu ileri yönde göstermişti; bu tablo geri yönde gösteriyor.

Kaybın büyüklüğü eksenden eksene üç kat değişiyor. En pahalı kapanış biçim ekseninindir: 7 kusur, bulunan 15’e iner. Ardından gerçekleştirim gelir: 6 kusur, bulunan 16. Arayüz, test ve belge eksenlerinin her biri 3 kusura mal olur ve üçünde de bulunan 19’da durur.

Belge ekseni bu tabloda en ucuz kapanışlardan biri görünüyor ve bu görüntü dersin uyarısıdır. Tablo kaç kusur kaçtığını sayıyor; kaçan kusurun bedelinin ne zaman ödendiğini saymıyor. Bir gerçekleştirim kusuru çalıştırıldığında ödenir, bir kez. Bir belge kusuru her okunduğunda ödenir ve okuyan her kişi aynı yanlış bilgiyi alır. İki sayı aynı sütunda toplanıyor ama iki ayrı zamanda ödeniyor. Bu ayrım kurgunun dışındadır ve tablodan çıkarılamaz; tablo yalnız bulunan ve kaçan sayısını verir.

Tablonun bir satırı ilk dersin tablosuyla birebir örtüşüyor. Biçim ekseni kapatıldığında bulunan 15’tir; ilk derste “üç inceleyen, ayrı eksen” yapılandırması da 15 bulmuştu ve o kurulun kapsadığı eksenler arayüz, gerçekleştirim, test ve belgeydi — yani biçim dışındaki dört eksen. İki ayrı ölçüm, iki ayrı yoldan aynı sayıya varıyor. Bu bir rastlantı değil, toplanabilirliğin sonucudur: aynı eksen kümesi kaç kişiye dağıtılırsa dağıtılsın aynı kümeyi bulur.

Tablonun pratik kullanımı bir fiyat listesidir. Bir eksenin kapanması çoğu zaman açıkça verilmiş bir karar değildir; kimsenin o eksene atanmamış olmasıyla ya da o eksenin bulgusunun engelleyici sayılmamasıyla kendiliğinden olur. Tablo o kararın karşılığını önceden veriyor ve karşılıklar eşit değil: biçim ekseninin kapanması 7, gerçekleştirimin 6, ötekilerin 3’er kusura mal oluyor. “Bir eksen daha açalım” ile “bir kişi daha ekleyelim” arasındaki seçim de aynı ölçümün içinde: ikinci kararın getirisi üçüncü derste 0 ölçülmüştü, birincisinin getirisi burada 3 ile 7 arasında.

Sağdaki döküm sütunu her satırda aynı iki kelimeyi taşıyor: eksik gereksinim 2. Altı satırın altısında da orada duruyor, hiçbir eksen onu kaldırmıyor.

Yazılmış Belge ve Yazılmamış Gereksinim

Alt tablo bu iki sınıfı yan yana koyuyor ve aradaki farkın nerede olmadığını gösteriyor.

Belge sınıfının üç kusuru 2, 2 ve 3 numaralı öbeklerde. Eksik gereksinim sınıfının iki kusuru 2 ve 10 numaralı öbeklerde. İki sınıfın kusurları aynı öbekte buluşuyor: ikinci öbekte hem iki belge kusuru hem bir eksik gereksinim kusuru var. Aynı elli satır, aynı okuma, aynı inceleyen.

Belge ekseni açıldığında belge kaçan 0 oluyor; ikinci öbekteki iki belge kusuru bulunuyor. Aynı öbekteki eksik gereksinim kusuru bulunmuyor ve yazılmayan kaçan 2 olarak kalıyor. Belge ekseni kapatıldığında belge kaçan 3’e çıkıyor, yazılmayan kaçan yine 2.

Fark bu yüzden yer farkı değildir. İki kusur aynı öbekte duruyor ve okuma ikisinin de üzerinden geçiyor. Fark, bakılacak bir metnin olup olmamasıdır. Belge kusurunda ortada yazılmış bir cümle vardır ve o cümle kodla karşılaştırılabilir; eksik gereksinim kusurunda karşılaştırılacak bir cümle hiç yazılmamıştır.

Bu, belge ekseninin en çok karıştırılan yanıdır. Belge ekseni açık olduğunda bir incelemenin “belgeye de bakıldı” demesi doğrudur, ama bakılan şey yazılmış olandır. Yazılmamış bir gereksinim, belge ekseninin de dışındadır — çünkü belge ekseni de sonuçta iki metni karşılaştırır ve iki metinden biri yoksa karşılaştırma yapılamaz. Beş eksenin beşi de aynı tanımın içinde kalır: inceleme yazılana bakar.

Buradan belge ekseninin sınır durumu çıkar. Bir davranış hiç belgelenmemişse bu bir belge kusuru mudur, yoksa eksik gereksinim midir? Ayrım, metnin beklenip beklenmediğine bakar. Değişiklik yeni bir genel ad getirmişse o adın belgelenmesi beklenir ve eksikliği belge sınıfına düşer — ikinci bulgu türü tam olarak budur ve belge ekseni onu bulur. Buna karşılık değişikliğin hiç ele almadığı bir durum, belge ekseninin bekleyeceği bir metin üretmez ve altıncı sınıfta kalır.

Sınırın pratik karşılığı tek cümledir: belge ekseni, değişikliğin getirdiğinin belgelenmesini sorar; getirmediğinin ne olduğunu sormaz. İkinci soruyu soran şey inceleme değil, değişikliğin kapsamını belirleyen karardır.

Özet

• Belge ekseni tek bir metne değil iki metne bakar: kodun yaptığı iş ile metnin anlattığı iş. Bulgusu bir çelişkidir ve yalnız belgeyi okuyarak bulunamaz.
• Üç bulgu türü vardır: eskimiş metin (değişmediği için değişiklikte görünmez), eksik metin (eklenen adın karşılığı yok), çelişen metin (iki yerde iki ayrı davranış).
• Bir eksen kapatıldığında kayıp, o eksenin sınıf büyüklüğüne eşittir: 3, 6, 3, 3, 7. En pahalı kapanış biçim ekseninindir ve bulunanı 15’e indirir.
• Belge ekseni kapatıldığında bulunan 22’den 19’a iner. Tablo kaçan kusuru sayar, bedelin ne zaman ödendiğini saymaz: bir belge kusuru her okunduğunda yeniden ödenir.
• Belge kusurları 2, 2, 3, eksik gereksinim kusurları 2 ve 10 numaralı öbeklerde; ikinci öbekte ikisi birden var. Belge ekseni açıkken belge kaçan 0, yazılmayan kaçan yine 2’dir.
• Fark yer farkı değil metin farkıdır: belge kusurunda karşılaştırılacak bir cümle vardır, eksik gereksinimde yoktur.

Sonraki Adım

Tablonun en pahalı satırı biçim ekseninindir: kapatıldığında 7 kusur kaçar ve bulunan 15’e iner. Bu, beş eksenin en kalabalık sınıfıdır ve aynı zamanda görülmesi en az bilgi isteyen sınıftır. İki özelliğin bir arada bulunması onu ayrı bir soruya açıyor: bu eksen bir insanın okumasını gerektiriyor mu. Sonraki ders biçim ekseninin bir araca devredilmesini ölçer — bulunan toplam nasıl değişir, insanın bulgusunun sınıf dağılımı ne olur ve aynı sonucu vermek için kaç inceleyen gerekir.