Katkı Rehberleri

Önceki ders iş öğesinin zincirini ölçtü ve inceleme halkasının uzunluğunun tur sayısından geldiğini gösterdi. Turu uzatan şey ilk turda görülemeyendir; peki bir bulgunun ilk turda görülmesi gerekmeyen bir türü var mı? Var: yazan zaten biliyorsa hiç bulgu olmaz.

Bir ekibin içinde çalışan biri beklentilerin çoğunu daha önceki turlarda öğrenmiştir. Dışarıdan gelen biri öğrenmemiştir ve aynı beklentiyi kendi turlarında yeniden öğrenir. Katkı rehberi (contribution guide), bu öğrenmeyi turdan önceye taşıyan yazılı metindir. Bu dersin sorusu rehberde ne yazacağı değil — yazılı her beklentinin kaç tur eksilttiğidir, ve rehberin hiç dokunamadığı bir yer olup olmadığıdır.

Beklenti Nerede Öğrenilir

Bir beklenti üç yerden öğrenilebilir. Rehberden: yazan değişikliği göndermeden önce okur ve uyar. Turdan: inceleyen bulguyu yazar, yazan düzeltir, değişiklik yeniden gönderilir. Hiçbir yerden: beklenti kimsenin aklına gelmez ve değişiklik öyle tümleşir.

Üçünün maliyeti aynı değildir. Rehberden öğrenilen beklenti sıfır tur harcar; bulgu hiç doğmadığı için inceleme kuyruğuna hiç girmez. Turdan öğrenilen beklenti en az bir tur harcar ve her tur zincire bekleme yazar. Hiç öğrenilmeyen beklenti tur harcamaz ama kusur olarak kalır.

Rehberin ölçülebilir etkisi bu yüzden tur sayısında aranır, bulunan kusur sayısında değil. Rehber incelemenin gözünü açmaz; incelemeye gelen kusuru azaltır. Bu ayrım kursun ikinci iddiasının aynadaki görüntüsüdür: eksen eklemek bulunanı büyütür, rehber gireni küçültür.

Üçüncü yolun — hiç öğrenilmeyen beklentinin — bu ölçümde bir karşılığı vardır ve o eksik gereksinim sınıfıdır. Kimsenin yazmadığı, kimsenin sormadığı beklenti hiçbir eksende görünmez ve hiçbir turda konuşulmaz. Rehberin en ilginç sorusu da buradadır: yazılı bir metin, hiç konuşulmayan bir sınıfa dokunabilir mi?

Rehberde Ne Yazılı Olabilir

Rehber bir üslup metni değil, bir kabul koşulu listesidir. Her maddesi, karşılanmadığında bir inceleme turu doğuracak bir beklentiyi adlandırır. İyi yazılmış bir madde, yazanın göndermeden önce kendi başına doğrulayabileceği bir şey söyler.

# örnek katkı rehberi parçası — çalıştırılmamıştır

## Göndermeden önce
- Biçim: depo kökündeki biçim ayarı uygulanmış olmalı; elle biçim
  düzeltmesi ayrı bir değişiklik olarak gönderilir.
- Test: değiştirilen her genel davranış için en az bir doğrulayan
  test bulunmalı; yalnız çağrıyı tekrarlayan test sayılmaz.
- Belge: genel arayüz değiştiyse ilgili belge aynı değişiklikte
  güncellenir.
- Gereksinim beyanı: değişikliğin karşıladığı gereksinim, iş öğesi
  numarasıyla ve tek cümleyle açıklama alanına yazılır; karşılanmayan
  gereksinim varsa o da yazılır.

## İnceleme
- Bir değişiklik tek bir gereksinimi karşılar.
- Açıklama alanı boş gönderilen değişiklik incelemeye alınmaz.

Maddelerin yazımı ölçülebilirliği belirler. “Testler anlamlı olmalı” bir madde değildir; yazan onu göndermeden önce denetleyemez ve inceleyen ondan bir bulgu türetemez. “Değiştirilen her genel davranış için en az bir doğrulayan test bulunmalı” ise denetlenebilir bir koşuldur: bakış açısı değişse de yanıtı evet ya da hayırdır. Aynı fark ikinci bölümde de görünür — “açıklama alanı boş gönderilen değişiklik incelemeye alınmaz” bir kapıdır ve uygulanabilir; “açıklamalar yeterli olmalı” bir dilektir.

Dört maddenin ilk üçü kolay tanınır: biçim, test ve belge, incelemenin baktığı beşin üçüdür. Dördüncü madde başkadır ve ölçümün asıl sorusu odur. Gereksinim beyanı, yazandan değişikliğin ne yapması gerektiğini yazmasını ister. İnceleme yazılana bakar; rehber, yazanı gereksinimin kendisini yazmaya zorlayarak incelemenin bakabileceği yüzeyi genişletir.

Ölçümün varsayımları:

• EA8 — Ortak tanımın 600 satırlık değişikliği ve 24 kusuru olduğu gibi kullanılır; sınıf dağılımı ve kâhin kursun sabitidir. degisiklik değiştirilmez.
• EA9 — Rehber incelemeden önce çalışır: kapsamındaki sınıfların kusurları yazan tarafından gönderilmeden giderilir ve incelemeye hiç girmez. Rehber bir eksen değildir; kusur bulmaz, kusurun doğmasını engeller.
• EA10 — Rehberin kapsamı bir sınıf listesidir. Dört kapsam denenir ve her biri bir öncekinin üstüne bir sınıf ekler; beşincisi eksik gereksinim sınıfını ekler.
• EA11 — Kapsamdaki her sınıfın bütün kusurları giderilir. Bu bir üst sınırdır; kısmen uyulan bir rehberin etkisi bu sayıların altında kalır.
• EA12 — İnceleme iki atamayla yürütülür: beş eksene bakan tek inceleyen, ve aynı eksene bakan üç inceleyen. Dikkat 12 öbekte sabittir ve 600 satır 12 öbektir; okunmayan öbek yoktur.
• EA13 — Tur döngüsü ortak tanımdan gelir ve tur başına 6 birim bekleme yazar. Turun girdisi artık 24 değil, rehberden geçen kusur sayısıdır.
• EA14 — Kümenin çözünürlüğü 24 kusurda 1/24’tür; tur ölçeğinde ölçülebilen en küçük fark 1 tur, yani 6 birim beklemedir.

Ölçüm

"""Katki rehberi: yazili beklentinin kapattigi inceleme turu.

Rehber incelemeden once calisir: kapsamindaki siniflarin kusurlarini
yazan gondermeden giderir. Degisiklik ve sinif listesi degismez.
"""
TOHUM = 20260815
EKSENLER = ("arayuz", "gerceklestirim", "test", "belge", "bicim")
YAZILMAYAN = "eksik gereksinim"
SINIFLAR = EKSENLER + (YAZILMAYAN,)
DIKKAT, OBEK = 12, 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 rehberden_gecen(d, kapsam):
    """Rehberin kapsamindaki sinif gonderilmeden once giderilir."""
    return [k for k in d["kusurlar"] if k["sinif"] not in kapsam]


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


def kurul(kusurlar, obek, atamalar, dikkat=DIKKAT):
    bulunan = set()
    for eksenler in atamalar:
        bulunan |= incele(kusurlar, obek, eksenler, dikkat)
    return bulunan


def tur_dongusu(bulunan, kusur_sayisi, tur_basina_bekleme=6):
    kalan, tur, bekleme = kusur_sayisi - len(bulunan), 1, tur_basina_bekleme
    while kalan > 0 and tur < 6:
        tur += 1
        bekleme += tur_basina_bekleme
        kalan -= max(1, len(bulunan) // 2)
    return tur, bekleme, max(0, kalan)


TAM = set(EKSENLER)
REHBERLER = {
    "rehber yok": set(),
    "biçim yazılı": {"bicim"},
    "biçim, test": {"bicim", "test"},
    "biçim, test, belge": {"bicim", "test", "belge"},
    "üçü + gereksinim beyanı": {"bicim", "test", "belge", YAZILMAYAN},
}
ATAMALAR = {"tek inceleyici, tüm eksenler": [TAM],
            "üç inceleyici, aynı eksen": [{"gerceklestirim"}] * 3}
d = degisiklik(600)
dagilim = {s: sum(1 for k in d["kusurlar"] if k["sinif"] == s) for s in SINIFLAR}
print("sınıf dağılımı: " + ", ".join(f"{s} {n}" for s, n in dagilim.items()))

for atama_adi, atama in ATAMALAR.items():
    print()
    print(atama_adi)
    print(f"{'rehber kapsamı':<25s} {'giderilen':>9s} {'giren':>5s} "
          f"{'bulunan':>7s} {'kaçan':>5s} {'yazılmayan':>10s} {'tur':>3s} "
          f"{'bekleme':>7s} {'kalan':>5s}")
    for ad, kapsam in REHBERLER.items():
        giren = rehberden_gecen(d, kapsam)
        b = kurul(giren, d["obek"], atama)
        kacan = [k for k in giren if k["no"] not in b]
        yaz = sum(1 for k in kacan if k["sinif"] == YAZILMAYAN)
        tur, bekleme, kalan = tur_dongusu(b, len(giren))
        print(f"{ad:<25s} {24 - len(giren):9d} {len(giren):5d} {len(b):7d} "
              f"{len(kacan):5d} {yaz:10d} {tur:3d} {bekleme:7d} {kalan:5d}")

sınıf dağılımı: arayuz 3, gerceklestirim 6, test 3, belge 3, bicim 7, eksik gereksinim 2

tek inceleyici, tüm eksenler
rehber kapsamı            giderilen giren bulunan kaçan yazılmayan tur bekleme kalan
rehber yok                        0    24      22     2          2   2      12     0
biçim yazılı                      7    17      15     2          2   2      12     0
biçim, test                      10    14      12     2          2   2      12     0
biçim, test, belge               13    11       9     2          2   2      12     0
üçü + gereksinim beyanı          15     9       9     0          0   1       6     0

üç inceleyici, aynı eksen
rehber kapsamı            giderilen giren bulunan kaçan yazılmayan tur bekleme kalan
rehber yok                        0    24       6    18          2   6      36     3
biçim yazılı                      7    17       6    11          2   5      30     0
biçim, test                      10    14       6     8          2   4      24     0
biçim, test, belge               13    11       6     5          2   3      18     0
üçü + gereksinim beyanı          15     9       6     3          0   2      12     0

Turların Okunması

İki tablo aynı rehberleri iki ayrı inceleme altında ölçüyor ve sonuçları taban tabana zıt.

Dar incelemede — üç inceleyen aynı eksene bakıyor — rehber her sınıf eklendiğinde bir tur eksiltiyor: 6, 5, 4, 3, 2. Bekleme 36’dan 12’ye iniyor; üçte ikisi kalkıyor. Bulunan sütunu ise beş satırın beşinde de 6’da duruyor. Rehber bir tek kusur daha buldurmadı; yalnız turların yiyeceği kusuru azalttı ve döngüyü erken bitirdi.

Geniş incelemede — tek inceleyen beş eksene birden bakıyor — ilk dört satır 2 tur / 12 bekleme ile aynı. Kapsam üç sınıfa çıksa bile tur sayısı kımıldamıyor. Nedeni tablonun solunda: bu incelemede kaçan zaten 2’de sabit ve döngü ikinci turda bitiyor; kısaltacak tur yok. Rehber burada turu değil, turun içindeki işi azaltıyor — giren 24’ten 11’e, bulunan 22’den 9’a iniyor.

Geniş incelemenin beşinci satırı bu sabitliği kırıyor: tur 1’e, bekleme 6’ya iniyor. Kursta bir turda kapanan tek yapılandırma budur. Nedeni tabloda okunuyor — kaçan 0. Döngü ikinci tura ancak kalan kusur varsa geçer; kalan yoksa ilk tur onaydır ve iş biter.

Buradan iki cümlelik bir sonuç çıkar. Katkı rehberi, incelemenin dar olduğu yerde tur satın alır; geniş olduğu yerde iş azaltır. İki kazanç da gerçektir ama aynı şey değildir ve aynı sayıya bakılarak görülmez: birincisi bekleme sütununda, ikincisi giren sütununda okunur.

İlk satırdaki 6 tur / 36 bekleme / 3 kalan ile ikinci satırdaki 5 tur / 30 bekleme / 0 kalan arasındaki fark ayrıca dikkate değer. Tek bir sınıfın rehbere yazılması yalnız bir tur eksiltmedi; kalan kusuru da sıfırladı. Döngü altı tur sınırına dayanmadan bittiği için kapanmamış kusur kalmadı. Önceki dersin ölçtüğü 50 birimlik yeniden açılma bedeli bu satırda ortadan kalkıyor.

Rehberin Yazılmayana Uzanması

Beşinci satır kursun boyunca ilk kez başka bir şey gösteriyor. Eksik gereksinim sınıfı şimdiye kadar her yapılandırmada 2 kaçanla duruyordu; burada 0. Kaçan toplamı da geniş incelemede 0’a iniyor — 24 kusurluk kümede kaçanın sıfırlandığı tek satır budur.

Bunun nedeni bir eksenin nihayet o sınıfa bakması değildir. Eksen listesi değişmedi; hiçbir inceleyen yeni bir yere bakmıyor. Değişen şey, kusurun sınıfının değişmesidir. Gereksinim beyanı istendiğinde yazan, değişikliğin ne yapması gerektiğini metne yazar; yazılmamış olan yazılmış olur ve artık incelemenin bakabildiği bir yüzeyde durur.

Bu, kursun dördüncü okumasının tek gerçek karşı örneğidir ve okumayı çürütmez, sınırını belirler. Hiçbir eksen yazılmayanı görmez doğrudur; çare ekseni değiştirmek değil, yazılmayanı yazdırmaktır. İnceleme sürecinin dışında duran bir düzenek — bir rehber maddesi — incelemenin göremediği sınıfı incelemenin görebileceği sınıfa çevirir.

Ölçünün çözünürlüğüne dikkat: iki kusur, 24’lük kümede 2/24’tür. Bu, kümenin en küçük biriminin iki katıdır ve savunulabilir. Bir kusurluk bir fark bu kümeyle savunulamazdı.

Rehberin Okunduğu An

Ölçüm bir üst sınırı veriyor. EA11 kapsamdaki her sınıfın bütün kusurlarının giderildiğini varsayıyor; gerçekte uyulma oranı bunun altındadır ve tablodaki kazançlar aynı oranda küçülür. Biçim kusurlarının yarısı giderilseydi giderilen 7 değil 3 ya da 4 olurdu, dar incelemede tur 5 yerine 6’da kalabilirdi. Rehberin değeri metnin içeriğinden çok kaçının uyulduğuna bağlıdır.

Uyulma oranını belirleyen şey rehberin nerede okunduğudur. Depo kökünde duran ve bir kez okunan bir metin, gönderme anından uzaktır; o an geldiğinde madde hatırlanmaz. Aynı maddenin gönderme yüzeyinde bir denetim listesi olarak karşıya çıkması, metni her gönderimde yeniden okutur. İkisi aynı cümleyi taşır ve aynı sonucu vermez.

İkinci belirleyici, maddenin doğrulanabilirliğidir. Yazanın kendi başına denetleyemediği bir madde atlanır; atlanan madde yalnız kendi kazancını kaybettirmez, listenin tamamının okunma alışkanlığını da zayıflatır. Bu yüzden rehberi uzatmak ters yönde çalışabilir: kırk maddelik bir listede uyulan madde oranı, dört maddelik bir listedekinden düşüktür.

Ölçüm bunun için bir eşik verir. Bir maddenin tabloda görünen en küçük etkisi 1 tur, yani 6 birim beklemedir. Hiçbir kapsamda tur ya da giren sayısını değiştirmeyen bir madde, rehberde yer kaplar ve ölçülebilir bir karşılığı yoktur.

Rehberin Kapatamadığı

Beşinci satır dar incelemede de kaçanı 3’e indiriyor ama sıfırlamıyor. Kalan üç kusur gerceklestirim dışındaki eksenlerde duruyor ve rehberin kapsamına girmiyor: arayuz sınıfı her iki tabloda da hiçbir rehber maddesiyle kapatılmadı.

Bunun bir nedeni var. Rehber, yazanın kendi başına doğrulayabileceği beklentileri yazabilir. Biçim ayarının uygulanıp uygulanmadığı, testin var olup olmadığı, belgenin güncellenip güncellenmediği — üçü de gönderilmeden önce tek başına denetlenebilir. Bir arayüz kararının doğru olup olmadığı ise ancak başka biri tarafından değerlendirilebilir; rehbere yazılabilecek hâli yoktur, çünkü kabul koşulu değil yargı gerektirir.

Sınır bu yüzden keskindir: rehber, denetlenebilir beklentileri kapatır; yargı gerektiren eksenler incelemede kalır. Rehberi şişirmek bu sınırı aşmaz, yalnız okunmaz bir metin üretir ve okunmayan madde hiçbir tur eksiltmez — tabloda görünmeyen bu satırın değeri her zaman 0 tur’dur.

Özet

• Katkı rehberi beklentiyi turdan önceye taşır: kapsamındaki sınıfın kusurları incelemeye hiç girmez. Rehber bir eksen değildir; bulunanı büyütmez, gireni küçültür.
• Dar incelemede rehber kapsamı büyüdükçe tur 6, 5, 4, 3, 2 olarak iner ve bekleme 36’dan 12’ye düşer; bulunan beş satırın beşinde de 6’da kalır.
• Geniş incelemede tur ilk dört satırda 2’de sabittir; rehber orada tur değil iş azaltır — giren 24’ten 11’e, bulunan 22’den 9’a iner.
• Tek bir sınıfın yazılması dar incelemede kalan kusuru 3’ten 0’a indirir ve önceki dersin 50 birimlik yeniden açılma bedelini ortadan kaldırır.
• Gereksinim beyanı isteyen rehber, eksik gereksinim kaçanını 2’den 0’a düşürür; sınıf incelemenin görebileceği yüzeye taşındığı için, yeni bir eksen eklendiği için değil.
• Rehber yalnız yazanın tek başına doğrulayabileceği beklentileri kapatır; arayuz gibi yargı gerektiren eksenler her kapsamda incelemede kalır.

Sonraki Adım

Rehber kimin neyi yapacağını değil, neyin karşılanacağını yazar. Değişiklik gönderildikten sonra bir soru daha doğar: kim bakacak? Kimi depoda bu soru serbesttir, kimi depoda dosya yoluna bağlı bir kural yanıtlar — bir dizinin sahibi vardır ve o dizine dokunan her değişiklik sahibinin onayını bekler. Sonraki ders bu kuralı ölçer: kod sahipliği ve zorunlu inceleyen, eksen çeşitliliğini artırır mı yoksa daraltır mı? Zorunlu inceleyen sayısını üçe çıkarmak bulunanı büyütür mü — yoksa kursun ikinci iddiası burada tersinden mi görünür?