Depo Belgeleri

Önceki iki ders dört türü ürünün çevresinde ölçtü: öğretici, nasıl yapılır, açıklama ve referans, hepsi ürünün ne yaptığını anlatan metinlerdi. Deponun içinde bunlardan başka belgeler de durur ve okurları ürünün okuru değildir. Depoya ilk kez bakan biri ürünü değil bu deponun ne olduğunu sorar; katkı vermek isteyen kişi ürünü değil buranın düzenini sorar; bir kararın gerekçesini arayan kişi ise ne ürünü ne düzeni, geçmişte verilmiş bir yargıyı sorar.

Bu ders üç depo belgesini aynı ölçüye sokar: tanıtım dosyası, katkı rehberi ve mimari karar kaydı. Soru yine aynı — her belge hangi yüzeye bağlanıyor ve ne kadar dayanıyor — ama bu kez yanıt bakım önceliğine dönüşecek, çünkü üç belge aynı ilgiyi hak etmiyor.

Üç Belge, Üç Okur Rolü

Tanıtım dosyası deponun kapısıdır ve en geniş okur kümesine bakar. Yanıtladığı sorular sırayla şunlardır: bu ne, kime yarar, nasıl kurulur, ilk çıktı nasıl alınır, ayrıntı nerede. Beşinci soru önemlidir: tanıtım dosyasının işi anlatmak değil, yönlendirmektir. İçine öğretici de referans da sığmaz; sığdırıldığında bir önceki dersin ölçtüğü karışım bedeli doğar. Bu, depo belgelerinin en sık görülen bozulma biçimidir: tanıtım dosyası zamanla dokümantasyonun tamamına dönüşür, çünkü her yeni bilgiyi oraya eklemek en kısa yoldur. Sonuç, tek bir dosyada toplanmış ve ayrı hızlarda çürüyen bir iddia yığınıdır; hangi bölümün ne zaman yanlışlandığı artık okunamaz.

Katkı rehberi dar bir okura bakar: koda dokunacak kişi. Yanıtladığı sorular geliştirme ortamının nasıl kurulacağı, testlerin nasıl çalıştırılacağı, dalın nasıl adlandırılacağı ve gönderilen işin nasıl karşılanacağıdır. Yazılı bir beklentinin inceleme turlarını nasıl kısalttığı Kod İnceleme ve Ekip Süreci kursunda ölçüldü ve burada tekrarlanmaz; bu derste katkı rehberi bir süreç aracı olarak değil, bakımı gereken bir metin olarak sayılır.

Mimari karar kaydı en dar okura bakar ve tek bir soruya yanıt verir: bu neden böyle kararlaştırıldı? Kaydın yapısı — bağlam, karar, sonuçlar — ve mimari kararın nasıl belgeleneceği Mimari Karar ve Dokümantasyon kursunun konusudur ve burada tekrarlanmaz. Bu derste karar kaydı yalnız hangi yüzeylere bağlandığıyla ve ömrüyle ölçülür.

# kurgu deponun üç belgesinin iskeleti
# örnek metin, çalıştırılmamıştır

tanıtım dosyası        Ölçüm İstasyonu nedir  (kavram)
                       Kurulum, ilk çalıştırma  (akış)
                       `istasyon baslat` seçenekleri  (imza)
                       Paket adı, dizin adları, bağlantılar  (ad)

katkı rehberi          Neden bu düzen  (kavram)
                       Ortam kurma, test, gönderme adımları  (akış)
                       Test komutunun seçenekleri  (imza)
                       Dal adlandırma düzeni, etiket adları  (ad)

mimari karar kaydı     Bağlam, karar, sonuçlar  (kavram)
                       Kararın bağladığı arayüz  (imza)
                       Bileşen adları  (ad)

Neye Bağlandıkları

İskelet üç belgenin karışımını doğrudan gösteriyor ve üçü birbirine benzemiyor.

Tanıtım dosyası dört yüzeyin dördüne birden bağlanır. İçinde bir kurulum akışı, bir komut imzası, bir ürün adı ve bir gerekçe cümlesi bir arada durur. Bu, tanıtım dosyasını deponun en karma belgesi yapar; bakımı da bu yüzden en zordur, çünkü onu bozan olayların sayısı en fazladır.

Katkı rehberi akış ağırlıklıdır: yazdığı şeyin çoğu bir sıradır. Adım anlatan her metin gibi, adımların kendisi değiştiğinde çöker. İkinci ağırlığı addır — dal adlandırma düzeni, etiket adları, dizin adları. Ad yüzeyi yavaş değişir ama değiştiğinde katkı rehberinin söylediği hiçbir şey hata vermez; yeni gelen kişi yanlış adlandırılmış bir dal açar ve bunu ancak biri söylerse öğrenir.

Mimari karar kaydı neredeyse tümüyle kavrama bağlıdır. Bir kararın bağlamı ve sonucu, kod değiştiği için değişmez; ancak kararın kendisi yeniden ele alındığında değişir. Karşılığında karar kaydında çalıştırılabilir hiçbir şey yoktur: bir karar kaydı çalışmaz, dolayısıyla yanlışlandığında ses de çıkarmaz.

Yönlendirmenin Ucuzluğu

Tanıtım dosyasının beşinci sorusu — ayrıntı nerede — ilk dördü kadar masum değildir, çünkü yanıtı yazarın elindedir. Aynı bilgi iki biçimde konabilir: anlatılarak ya da işaret edilerek.

Kurulum bölümü örnek olsun. Bütün seçenekleri tanıtım dosyasına dökmek, oraya bir yığın imza iddiası taşımak demektir; imza iki sürümde bir değişir. Aynı bölüm “seçeneklerin tümü referansta” diyerek tek bir işaretle geçilirse, taşınan şey bir ad iddiasına iner ve ad beş sürümde bir değişir — imzadan iki buçuk kat yavaş. Bilgi kaybolmaz, yalnız bir kez yazılır ve tanıtım dosyası ona bağlanır.

Bunun bedeli de var: bağlantı hedefleri de bayatlar ve bir bağlantı koptuğunda okur hiçbir şey bulamaz. Ama iki kusur eşit değildir. Kopmuş bir bağlantı okurun fark ettiği bir kusurdur; yanlış yazılmış bir seçenek listesi okurun fark etmediği bir kusurdur. Tanıtım dosyasını yönlendirici yazmak, sessiz kusuru gürültülü kusura çevirir — kursun boyunca aynı takas birkaç kez daha karşımıza çıkacak.

Aşılmış Kayıt

Mimari karar kaydının ölçümde görünmeyen bir özelliği var. Öteki iki belge yanlışlandığında düzeltilir; karar kaydı yanlışlandığında düzeltilmez, aşılır. Kaydın kendisi olduğu gibi durur ve yeni bir kayıt onu geçersiz ilan eder.

Bu, ölçüyü ortadan kaldırmaz ama sonucunu değiştirir. Bir kaydın kavram iddiaları bugünkü sistem için yanlışsa o kayıt bayattır — tablo bunu on ikinci sürümde 0/10 ile söylüyor. Ama kayıt tarih olarak okunuyorsa, iddiaları verildikleri andaki sistem için hâlâ doğrudur. Farkı tek bir alan taşır: kaydın durumu. Durum yazılmışsa okur baktığı metnin bugünü mü yoksa geçmişi mi anlattığını bilir; yazılmamışsa on yıllık bir gerekçeyi güncel sanarak okur.

Bu, kursun boyunca görülen tek düzeltme biçimidir ki metni değiştirmez: sessiz bayatlamayı susturmanın bir yolu, iddiayı düzeltmek yerine kapsamını yazmaktır. Bir cümlenin hangi sürüm için doğru olduğunu söylemek, onu yanlışlıktan çıkarıp tarihe taşır.

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

• DT18 — Kurgu depoda üç belge vardır: tanıtım dosyası, katkı rehberi ve mimari karar kaydı. Depoda bulunabilecek başka belgeler bu ölçümün dışındadır.
• DT19 — Yüzeyler ve sıklıkları önceki derslerdekiyle aynıdır: imza 2, akış 3, ad 5, kavram 12 sürümde bir. Bu dört sayı değiştirilmez.
• DT20 — Belgelerin yüzey karışımı yazım biçiminden gelir ve iskelette gösterildiği gibidir; karışım ölçüm boyunca sabit tutulur.
• DT21 — Tanıtım dosyası 12, katkı rehberi 12, mimari karar kaydı 10 iddia taşır. İlk iki belgenin eşit iddia taşıması kasıtlıdır: fark uzunluktan gelmesin.
• DT22 — Çalıştırılabilir örneğe gömülü iddia oranı tanıtım dosyasında 0,50, katkı rehberinde 0,40, mimari karar kaydında 0,00’dır. Kavrama bağlı iddia gömülemez.
• DT23 — Bir iddia, bağlandığı yüzey ölçülen sürüme kadar en az bir kez değiştiyse bayattır ve kimse düzeltmez.
• DT24 — İlk kayıp sürümü, belgenin ilk bayat iddiasını verdiği sürümdür. Yarılanma sürümü, doğru kalan iddia payının 0,5’in altına indiği ilk sürümdür.
• DT25 — Ölçüm 0, 2, 3, 5, 6 ve 12’nci sürümleri kurar; bu sürümler yüzey sıklıklarının eşiklerine denk gelsin diye seçilmiştir.
• DT26 — Kümenin çözünürlüğü belge başına 1/12, 1/12 ve 1/10’dur; tek iddialık farkların altı bu kümeyle savunulamaz.

Ölçüm

"""Depo belgeleri: her belgenin bagli oldugu yuzey karisimi ve omru.

Bolum 1 - uc belgenin yuzey karisimi ve gomulu iddia sayisi.
Bolum 2 - surum boyunca dogru/bayat/sessiz, ilk kayip ve yarilanma surumu.
"""
SIKLIK = {"imza": 2, "akis": 3, "ad": 5, "kavram": 12}
SURUMLER = (0, 2, 3, 5, 6, 12)
# Uc depo belgesi: okuma sirasina gore yuzey karisimi.
BELGELER = {
    "tanıtım dosyası":   {"kavram": 2, "akis": 4, "imza": 3, "ad": 3},
    "katkı rehberi":     {"kavram": 1, "akis": 6, "imza": 2, "ad": 3},
    "mimari karar kaydı": {"kavram": 7, "akis": 0, "imza": 1, "ad": 2},
}
# Calistirilabilir ornege gomulu iddia orani.
ORNEKLI = {"tanıtım dosyası": 0.50, "katkı rehberi": 0.40,
           "mimari karar kaydı": 0.00}


def iddialar():
    liste, no = [], 0
    for belge, dagilim in BELGELER.items():
        gomulu_hedef = 0
        for yuzey, adet in dagilim.items():
            for _ in range(adet):
                no += 1
                gomulu_hedef += ORNEKLI[belge]
                gomulu = gomulu_hedef >= 1 and yuzey != "kavram"
                if gomulu:
                    gomulu_hedef -= 1
                liste.append({"no": no, "belge": belge, "yuzey": yuzey,
                              "gomulu": gomulu})
    return liste


def bayat_mi(i, surum):
    return surum // SIKLIK[i["yuzey"]] >= 1


def olc(belge, surum, liste):
    grup = [i for i in liste if i["belge"] == belge]
    bayat = [i for i in grup if bayat_mi(i, surum)]
    sessiz = [i for i in bayat if not i["gomulu"]]
    return len(grup), len(grup) - len(bayat), len(bayat), len(sessiz)


L = iddialar()
print(f"belge {len(BELGELER)} | iddia {len(L)} | "
      f"örneğe gömülü {sum(i['gomulu'] for i in L)}")
print()
print(f"{'belge':<20s} {'iddia':>5s} {'kavram':>6s} {'akış':>5s} {'imza':>5s} "
      f"{'ad':>4s} {'gömülü':>6s}")
for b in BELGELER:
    g = [i for i in L if i["belge"] == b]
    print(f"{b:<20s} {len(g):5d} "
          + " ".join(f"{sum(1 for i in g if i['yuzey'] == y):>{w}d}"
                     for y, w in zip(("kavram", "akis", "imza", "ad"),
                                     (6, 5, 5, 4)))
          + f" {sum(i['gomulu'] for i in g):6d}")

print()
print(f"{'sürüm':>5s} " + " ".join(f"{b:>20s}" for b in BELGELER))
print(f"{'':5s} " + " ".join(f"{'doğru/bayat/sessiz':>20s}" for _ in BELGELER))
for s in SURUMLER:
    print(f"{s:5d} " + " ".join(
        f"{'{}/{}/{}'.format(*olc(b, s, L)[1:]):>20s}" for b in BELGELER))

print()
print(f"{'belge':<20s} {'ilk kayıp':>9s} {'yarılanma':>9s} "
      f"{'12. sürümde doğru':>17s} {'sessiz':>6s}")
for b in BELGELER:
    toplam = olc(b, 0, L)[0]
    ilk = next(s for s in range(1, 13) if olc(b, s, L)[2] > 0)
    yari = next((s for s in range(1, 13) if olc(b, s, L)[1] / toplam < 0.5), 0)
    _, dogru, _, sessiz = olc(b, 12, L)
    print(f"{b:<20s} {ilk:9d} {yari:9d} {f'{dogru}/{toplam}':>17s} "
          f"{sessiz:6d}")

belge 3 | iddia 34 | örneğe gömülü 10

belge                iddia kavram  akış  imza   ad gömülü
tanıtım dosyası         12      2     4     3    3      6
katkı rehberi           12      1     6     2    3      4
mimari karar kaydı      10      7     0     1    2      0

sürüm      tanıtım dosyası        katkı rehberi   mimari karar kaydı
        doğru/bayat/sessiz   doğru/bayat/sessiz   doğru/bayat/sessiz
    0               12/0/0               12/0/0               10/0/0
    2                9/3/2               10/2/1                9/1/1
    3                5/7/3                4/8/5                9/1/1
    5               2/10/4               1/11/7                7/3/3
    6               2/10/4               1/11/7                7/3/3
   12               0/12/6               0/12/8              0/10/10

belge                ilk kayıp yarılanma 12. sürümde doğru sessiz
tanıtım dosyası              2         3              0/12      6
katkı rehberi                2         3              0/12      8
mimari karar kaydı           2        12              0/10     10

Ömürlerin Okunması

Alt tablonun ilk sütunu bir tuzağı kapatıyor: ilk kayıp sürümü üç belgede de 2. Üçünün de içinde en az bir imza iddiası var, dolayısıyla üçü de ilk kaybını aynı anda veriyor. Bir belgenin “eskimeye başladığı” an hiçbir şey ayırt etmez; her belge aynı anda eskimeye başlar.

Ayırt eden şey eğimdir. Yarılanma sürümü tanıtım dosyasında 3, katkı rehberinde 3, mimari karar kaydında 12. İlk iki belge üç sürüm içinde yarısını kaybederken karar kaydı aynı noktada 9/10 ile duruyor. Aradaki dört kat, yazım kalitesinden değil, karışımdan geliyor: karar kaydının 7 iddiası kavrama bağlı ve kavram on iki sürümde bir değişiyor.

Beşinci sürüm satırı tabloyu en iyi özetleyen satır. Orada tanıtım dosyası 2/10/4, katkı rehberi 1/11/7, karar kaydı 7/3/3 veriyor. Aynı depoda, aynı gün yazılmış üç belge; beş sürüm sonra birinin onda yedisi ayakta, ötekilerin on ikide biri. Bakım bütçesi eşit dağıtılırsa üçte ikisi boşa gider — karar kaydına ayrılan bakım, tanıtım dosyasına ayrılana göre dört kat daha az iş görür.

Sessiz sütunu ise ödünleşmeyi tersine çeviriyor. On ikinci sürümde üç belgenin üçü de tümüyle bayat; ama tanıtım dosyasının 12 bayat iddiasının 6’sı, katkı rehberinin 12’sinin 8’i, karar kaydının 10’unun 10’u sessiz. En uzun yaşayan belge, bozulduğunda en az duyulan belgedir. Tanıtım dosyasının kurulum bölümü kırıldığında bunu her yeni okur anında görür; karar kaydının artık geçersiz olduğunu kimse görmez, çünkü karar kaydı çalıştırılmaz — ve o kayda dayanarak yeni bir karar verilir.

Üçüncü sürüm satırı ayrıca katkı rehberinin özel durumunu veriyor: orada tanıtım dosyası 5/7/3, katkı rehberi 4/8/5. Akış yüzeyi tek bir kez değişti ve rehberin altı iddiasını birden aldı; rehber, tanıtım dosyasından daha hızlı çöktü. Bunun sıkıntısı okurunun kim olduğundan geliyor. Katkı rehberini okuyan kişi tanım gereği depoya yeni gelendir; bir adımın artık geçerli olmadığını anlayacak bilgiye sahip değildir ve yanlış adımı kendi hatası sanar. Deponun en yanlışlanabilir metni, yanlışı en az fark edebilecek okura veriliyor.

Buradan iki ayrı bakım kuralı çıkıyor. Tanıtım dosyası ve katkı rehberi sık ama ucuz bakım ister: gömülü örnekleri çalıştıran bir kontrol, tanıtım dosyasında altı, katkı rehberinde dört iddiayı kendiliğinden yakalar. Mimari karar kaydı seyrek ama pahalı bakım ister: onu ancak bir insan, kararın bağlamına dönerek doğrulayabilir. İki belgeyi aynı takvimle denetlemek her ikisini de yanlış yerde denetlemek olur.

Özet

• Depo belgelerinin okuru ürünün okuru değildir: tanıtım dosyası depoya ilk bakanı, katkı rehberi koda dokunacak olanı, mimari karar kaydı gerekçe arayanı karşılar.
• Tanıtım dosyası dört yüzeyin dördüne birden bağlanır (2/4/3/3), katkı rehberi akış ve ad ağırlıklıdır (1/6/2/3), mimari karar kaydı kavram ağırlıklıdır (7/0/1/2).
• İlk kayıp sürümü üçünde de 2’dir ve hiçbir şey ayırt etmez; ayırt eden yarılanma sürümüdür: tanıtım dosyası 3, katkı rehberi 3, karar kaydı 12.
• Beşinci sürümde karar kaydı 7/3/3 ile ayakta, tanıtım dosyası 2/10/4, katkı rehberi 1/11/7; eşit dağıtılan bakım bütçesi bu yüzden yanlış yere gider.
• En uzun yaşayan belge en sessiz bozulandır: on ikinci sürümde karar kaydının 10 bayat iddiasının 10’u sessiz, tanıtım dosyasının 12’sinin 6’sı.
• Anlatmak yerine işaret etmek iddiayı imzadan ada taşır ve ömrünü uzatır; karar kaydında ise durumu yazmak, bayat bir cümleyi yanlışlıktan çıkarıp tarihe taşır.

Sonraki Adım

Bu derste ölçülen üç belgenin hiçbirinde imza payı yarıyı geçmiyordu. Deponun en kalabalık imza kümesi başka yerde duruyor: arayüz referansında. İkinci ders onu 2/15 ile bırakmıştı ve bunun nedeni yazarın özensizliği değil, on beş iddianın on üçünün en hızlı yüzeye asılı olmasıydı. Sonraki ders bu türü kendi düzeniyle ele alır — uç nokta, parametre ve hata nasıl belgelenir — ve tek bir soruyu ölçer: bu iddialar elle yazılmak zorunda mı, yazılmazsa ne kadarı kurtulur ve geriye tam olarak ne kalır?