Kod ile Birlikte Doküman

Buraya kadarki her ölçüm dokümanı yazıldığı andaki hâliyle aldı. Dört türü, yüzey dağılımlarını, başlık düzenini ve örneklerin çalışırlığını hep tek bir anda, sıfırıncı sürümde ölçtük. O anda doküman bir metindir ve metnin bütün iddiaları doğrudur.

Doküman o anda kalmaz. Anlattığı şey değişmeye devam eder ve doküman değişmezse iddia (claim) ile gerçeklik ayrışır. Bu dersin sorusu dokümanın nasıl yazıldığı değil, nerede durduğudur: doküman kodun yanında mı, ayrı bir yerde mi tutulur; değişiklikle aynı kayda mı girer, ayrı bir takvimde mi elden geçirilir. Üç işletim rejimi kuracağız ve aynı elli altı iddiayı on iki sürüm boyunca üçünde de izleyeceğiz.

Üç İşletim Rejimi

Ayrı takvim. Doküman kodun dışında yaşar; kendi deposu, kendi yayım düzeni vardır. Kimse onu bir değişiklikle birlikte açmaz. Belirli aralıklarla — kurgumuzda beş sürümde bir — biri oturur ve dokümanın tamamını gözden geçirir. O geçişte her iddia tazelenir, sonra doküman yeniden yalnız kalır.

Kodla birlikte sürümlenir. Doküman kaynak ağacının içindedir ve değişikliğin kendisiyle aynı kayda girer. Bu kod ile birlikte doküman (docs as code) yaklaşımının çekirdeğidir: doküman ayrı bir varlık değil, deponun bir dosyasıdır. Yazan, kodu değiştirdiği kaydın içinde dokümana da dokunabilir. Dokunmak zorunda değildir.

Kodla birlikte sürümlenir ve incelemeye girer. Değişiklik başkası tarafından okunur ve okuyan dokümanı da görür. Doküman satırları kod satırlarıyla aynı ekranda durduğu için “bu alanı yeniden adlandırdın, referansta eski adı duruyor” cümlesi kurulabilir hâle gelir.

Üç rejim aynı yazma çabasını harcar. Aralarındaki fark dokümanın ne zaman bakıldığıdır, ne kadar iyi yazıldığı değil.

Üçüncü rejimin iki koşulu vardır ve ikisi de yapısaldır. Birincisi, doküman dosyasının değişikliğin içinde bulunması: ayrı bir kayda alınan doküman düzeltmesi, düzelttiği kod değişikliğiyle aynı ekranda görünmez. İkincisi, eksik doküman güncellemesinin inceleyen tarafından bir kusur sınıfı sayılması: aynı listeye bakan iki kişiden biri dokunulmamış dosyayı bir eksiklik olarak okur, öbürü okumaz. Ölçüm ikinci koşulun sağlandığını varsayar; sağlanmadığında üçüncü rejim ikinciye çöker ve tablodaki fark ortadan kalkar.

İncelemenin Gördüğü Yüzey

İncelemenin kendi ekseni Kod İnceleme ve Ekip Süreci kursunda kuruldu: inceleme yalnız baktığı eksende ve okuduğu öbek kadarında görür. Burada o tartışma tekrarlanmıyor. Bize gereken tek şey şu sınırdır: inceleyen, değişikliğin içinde görüneni okur.

Bu sınır dört yüzeyi ikiye böler. İmza ve akış değişikliğin içinde görünür: bir alanın türü değiştiğinde ya da adımların sırası değiştiğinde bunu üreten satırlar kaydın içindedir, inceleyen ikisini de yan yana okur. Ad ve kavram görünmez: bir şeyin dışarıya verilen adı ürün tarafında değişir, bir gerekçe tartışmada değişir; ikisi de kaynak satırında bir iz bırakmayabilir. İnceleyen dokümanda eski adı okuduğunda onu yanlış sanmak için hiçbir nedeni yoktur.

Değişikliğin içinde dokümanın nerede durduğu da böyle görünür:

# ornek degisiklik listesi , calistirilmamistir

değişiklik: ölçüm arayüzüne birim alanı eklenir
  kaynak/olcum.py                  +14  -3
  kaynak/olcum_dogrula.py           +6  -0
  dokuman/referans/olcum.md         +9  -4
  dokuman/ogretici/ilk-olcum.md      0   0

Dördüncü satır bu dersin ilgilendiği satırdır. Referans güncellenmiş, öğretici hiç dokunulmamış. İnceleyen bu listeyi görür ve öğreticinin dokunulmamış olduğunu fark edebilir; ama fark etmesi için öğreticinin hangi iddiasının bu değişiklikten etkilendiğini bilmesi gerekir. Bildiği durum imza ve akış, bilemediği durum ad ve kavramdır.

Dokümanın Sürümü

Dokümanı kodun yanına koymanın incelemeden bağımsız ikinci bir sonucu vardır: doküman deponun sürümleme düzenine girer. Bir dalda yapılan doküman değişikliği o dala aittir; bir sürüm etiketi konduğunda o etiket dokümanı da işaret eder. Sürüm Kontrolüne Giriş kursunun kurduğu ölçüt burada doğrudan işler — kayıt nesne veritabanına yazılmışsa geri getirilebilir. Dokümanın üçüncü sürümdeki hâli, üçüncü sürüm etiketinden okunabilir.

Ayrı takvimle işletilen doküman bu özelliği taşımaz. Onun tek bir hâli vardır: şimdiki hâl. Üçüncü sürümü kullanan bir okur, altıncı sürümü anlatan bir metni okur ve aradaki farkı ölçemez. Bu, ölçtüğümüz bayatlamadan farklı bir yanlışlık türüdür: iddia bugünün kodu için doğrudur, okurun elindeki kod için yanlıştır. Ölçümümüz bunu saymaz, çünkü kâhin her sürümü tek tek bilir; gerçek bir kurulumda okurun hangi sürümde olduğu bilinmez ve bu belirsizlik doküman tarafından kapatılamaz.

Sürümleme kararının doğrudan bir bedeli de vardır. Doküman kodla aynı dalda ilerlerse, bir düzeltme yayımlanmış sürüme ancak o sürümün dalına taşınarak ulaşır; ayrı takvimde ise düzeltme herkese anında görünür. Kod ile birlikte doküman yaklaşımı doğruluğu sürüme bağlar ve bunun karşılığında yayım işini çoğaltır. Kurgumuz bu maliyeti ölçmez; ölçtüğü tek şey iddianın doğru kalıp kalmadığıdır.

Ölçümün Varsayımları

• DI1 — Elli altı iddia, dört tür ve dört yüzey ortak kurgudan alınır. Kâhin kurgunun kendisidir: hangi iddianın hangi yüzeye bağlı olduğunu ve hangi sürümde bayatladığını biz yazdığımız için biliriz.
• DI2 — Yüzey sıklıkları değişmez: imza iki sürümde bir, akış üçte bir, ad beşte bir, kavram on ikide bir değişir. Bir iddia bağlandığı yüzey değiştiği anda bayatlar (staleness).
• DI3 — Elli altı iddianın on yedisi çalıştırılabilir örneğe gömülüdür. Gömülü bir iddia bayatlayınca ses çıkarır: örnek çalışmaz. Gömülü olmayan bir iddia bayatlayınca hiçbir şey olmaz; bu sessiz bayatlamadır (silent staleness).
• DI4 — Ayrı takvim rejiminde doküman beşinci ve onuncu sürümde elden geçirilir ve o geçişte her iddia tazelenir. Ara sürümlerde kimse dokümana bakmaz.
• DI5 — Kodla birlikte sürümlenen rejimde yalnız gömülü iddialar onarılır: örnek çalışmadığı için bayatlama kendini duyurur ve aynı kayıtta düzeltilir.
• DI6 — İncelemeli rejimde gömülü iddialara ek olarak imza ve akış yüzeyine bağlı iddialar da onarılır; ad ve kavram yüzeyindekiler onarılmaz, çünkü değişikliğin içinde görünmezler.
• DI7 — Ölçünün birimi bayat sürüm-iddia sayısıdır: her sürümün sonunda bayat duran iddialar sayılır ve on iki sürüm boyunca toplanır. Üst sınır elli altı çarpı on iki, yani 672’dir.
• DI8 — Onarım, iddianın bayatladığı sürümün içinde olur. Rejimler arasındaki fark onarımın hızı değil, hangi iddiaya hiç dokunulmadığıdır.

Ölçüm

"""Dokumanin incelemeye girmesinin bayatlamaya etkisi.

Bolum 1 - uc isletim rejimi, on iki surum boyunca bayat kalinan surum sayisi.
Bolum 2 - yuzeylerin gomululuk ve incelemede gorunurluk dagilimi.
"""
TURLER = {
    "öğretici":     {"akis": 9, "imza": 3, "ad": 2, "kavram": 1},
    "nasıl yapılır": {"akis": 6, "imza": 5, "ad": 2, "kavram": 1},
    "açıklama":     {"akis": 1, "imza": 1, "ad": 1, "kavram": 9},
    "referans":     {"akis": 0, "imza": 13, "ad": 2, "kavram": 0},
}
SIKLIK = {"imza": 2, "akis": 3, "ad": 5, "kavram": 12}
ORNEKLI = {"öğretici": 0.60, "nasıl yapılır": 0.70, "açıklama": 0.10,
           "referans": 0.00}
GORULEN = ("imza", "akis")      # kod incelemesinin fark ettigi yuzeyler
ELDEN_GECIRME = (5, 10)         # ayri takvimde dokumanin gozden gecirildigi surum
SON = 12


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


def degisen(surum):
    return {y for y, s in SIKLIK.items() if surum % s == 0}


def onarir(rejim, iddia, surum):
    if rejim == "ayrı takvim":
        return surum in ELDEN_GECIRME
    if rejim == "birlikte sürümlenir":
        return iddia["gomulu"]
    return iddia["gomulu"] or iddia["yuzey"] in GORULEN


REJIMLER = ("ayrı takvim", "birlikte sürümlenir", "birlikte + inceleme")


def kosum(rejim, liste):
    dogru = {i["no"]: True for i in liste}
    borc = 0
    for surum in range(1, SON + 1):
        d = degisen(surum)
        for i in liste:
            if i["yuzey"] in d:
                dogru[i["no"]] = False
            if not dogru[i["no"]] and onarir(rejim, i, surum):
                dogru[i["no"]] = True
        borc += sum(1 for i in liste if not dogru[i["no"]])
    bayat = [i for i in liste if not dogru[i["no"]]]
    sessiz = [i for i in bayat if not i["gomulu"]]
    return borc, len(liste) - len(bayat), len(bayat), len(sessiz)


L = iddialar()
print(f"iddia {len(L)}, örneğe gömülü {sum(1 for i in L if i['gomulu'])}, "
      f"incelemenin gördüğü yüzey {sum(1 for i in L if i['yuzey'] in GORULEN)}")
print()
print(f"{'rejim':>20s} {'bayat sürüm-iddia':>18s} {'doğru':>6s} {'bayat':>6s} "
      f"{'sessiz':>7s}")
for rejim in REJIMLER:
    borc, dogru, bayat, sessiz = kosum(rejim, L)
    print(f"{rejim:>20s} {f'{borc}/{len(L) * SON}':>18s} {dogru:6d} {bayat:6d} "
          f"{sessiz:7d}")
print()
print(f"{'yüzey':>7s} {'iddia':>6s} {'gömülü':>7s} {'incelemede görünür':>19s}")
for y in SIKLIK:
    g = [i for i in L if i["yuzey"] == y]
    print(f"{y:>7s} {len(g):6d} {sum(1 for i in g if i['gomulu']):7d} "
          f"{'evet' if y in GORULEN else 'hayır':>19s}")

iddia 56, örneğe gömülü 17, incelemenin gördüğü yüzey 38

               rejim  bayat sürüm-iddia  doğru  bayat  sessiz
         ayrı takvim            299/672      7     49      35
 birlikte sürümlenir            300/672     17     39      39
 birlikte + inceleme             43/672     41     15      15

  yüzey  iddia  gömülü  incelemede görünür
   imza     22       5                evet
   akis     16       9                evet
     ad      7       3               hayır
 kavram     11       0               hayır

Sağdaki üç sütun on ikinci sürümün sonundaki durumu verir: kaç iddia doğru kalmış, kaçı bayat, bayatların kaçı sessiz.

Aynı Borç, Farklı Dağılım

İlk iki satırın toplamı neredeyse aynıdır: 299 ve 300. Ayrı takvimle işletilen bir doküman ile kodla birlikte sürümlenen ama incelemeye girmeyen bir doküman, on iki sürüm boyunca hemen hemen aynı süreyi yanlış durumda geçirir. Kodun yanına taşımak tek başına bir kazanç üretmemiştir.

Toplamlar eşit, dağılımlar tümüyle farklıdır. Ayrı takvimde hiçbir iddia kalıcı olarak bayat değildir — beşinci ve onuncu sürümdeki geçişler her şeyi sıfırlar — ama iki geçiş arasında her tür iddia bayat durur. On ikinci sürümde doğru kalan yalnız 7 iddia vardır ve bunlar son geçişten sonra yüzeyi hiç değişmemiş olanlardır: onuncu sürümde tazelenen ad iddiaları, çünkü ad beşte bir değişir ve bir sonraki değişimi on beşinci sürümdedir. Yedi sayısı ad yüzeyine bağlı iddia sayısının tamamıdır.

Bu, ayrı takvim rejiminin borcunun nereden geldiğini de açıklar. Elden geçirme aralığı en hızlı yüzeyin sıklığından büyükse, o yüzey iki geçiş arasında zaten bayatlar. Beş sürümlük aralık, iki sürümde bir değişen imzaya karşı hiçbir şey yapmaz: yirmi iki imza iddiası her geçişten sonraki ikinci sürümde yeniden yanlışa düşer ve bir sonraki geçişe kadar öyle kalır. Aralığı kısaltmak borcu düşürür ama okuma işini doğrusal olarak büyütür; her geçiş elli altı iddianın elle doğrulanması demektir.

Kodla birlikte sürümlenen rejimde tablo tersine döner: 17 iddia her zaman doğrudur ve 39 iddia on ikinci sürümde bayattır. On yedi sayısı tanıdıktır — tam olarak gömülü iddia sayısıdır. Otuz dokuz da tanıdıktır: bayatların hepsi sessizdir. Bu rejim gürültü çıkaranı hemen onarır, çıkarmayana hiç dokunmaz. Doküman kodun yanındadır, her değişiklikte gözün önünden geçer ve otuz dokuz iddia yıllarca yanlış kalır.

Kodla birlikte sürümlemek bir taşıma kararıdır, bir bakım kararı değildir. Dosyanın yerini değiştirmek kimseye onu okuma yükümlülüğü getirmez.

İncelemenin Kurtardığı ve Kurtaramadığı

Üçüncü satır borcu 300’den 43’e indirir — yedi kat. Fark tek bir şeyden gelir: inceleyen, değişikliğin dokunduğu yüzeye bağlı doküman iddialarını da okur. Alt tablo kapsamı verir: incelemenin gördüğü iki yüzeye 38 iddia bağlıdır, yani elli altının üçte ikisinden fazlası.

Geriye 15 iddia kalır ve tabloda hepsi sessizdir. Bunlar ad ve kavram yüzeyine bağlı, örneğe gömülü olmayan iddialardır: ad yüzeyinde 7 − 3 = 4, kavram yüzeyinde 11. Kavram sütunundaki gömülü sayısının sıfır olması kurgunun bir kuralıdır — bir gerekçe çalıştırılabilir bir örneğe gömülemez.

Bu on beş iddia üç rejimin hiçbirinde bir uyarı üretmez. Örnek çalışır, inceleme geçer, kimse şikâyet etmez. On ikinci sürümde doküman 41 doğru iddia taşır ve okur için oldukça iyi görünür; taşıdığı 15 yanlış cümlenin hiçbiri kendini göstermez. Kursun merkezindeki sorun tam burada belirir ve sonraki iki ders onun üstüne kurulur: bayatlamanın görünen bölümü ile var olan bölümü aynı şey değildir.

Rejimlerin bedeli de eşit değildir. Ayrı takvim iki tam gözden geçirme ister; elli altı iddianın hepsi iki kez elle doğrulanır. İncelemeli rejim hiç ek geçiş istemez, çünkü doğrulama zaten yapılan bir işin — değişikliğin okunmasının — içine yerleşir. Aradaki fark, doküman bakımının ayrı bir iş mi yoksa var olan bir işin bir alanı mı olduğu kararıdır.

Ölçünün Söylemediği

Üçüncü rejimin 43 sayısı bir alt sınırdır ve iyimserdir. Varsayım DI6 incelemenin gördüğü her iddiayı yakaladığını söyler; Kod İnceleme ve Ekip Süreci kursunun sonucu bunun doğru olmadığını gösterdi — inceleme baktığı eksende bile okuduğu öbek kadarını görür ve kaçırdığı kusur vardır. Doküman satırları o öbeğin en kolay atlanan bölümüdür, çünkü çalışmayı engellemezler. Gerçek bir kurulumda üçüncü satırın borcu 43’ün üstünde, ikinci satırın 300’ünün altında bir yerdedir.

İki sayı bu iyimserlikten etkilenmez. Ad ve kavram yüzeyindeki 15 iddia, inceleme ne kadar dikkatli olursa olsun bu rejimde yakalanamaz: değişikliğin içinde görünmezler, dolayısıyla bakacak bir yer yoktur. Gömülü 17 iddia da tersinden aynı ölçüde kesindir: bunlar incelemeye hiç gerek duymaz, çünkü örnek çalışmadığında kendini söyler. Rejim seçimi yalnız aradaki 24 iddianın kaderini değiştirir.

Özet

• Doküman üç rejimde işletilebilir: ayrı takvimde gözden geçirilerek, kodla birlikte sürümlenerek, ya da kodla birlikte sürümlenip incelemeye sokularak.
• Ayrı takvim 299/672, kodla birlikte sürümleme 300/672 bayat sürüm-iddia üretir; ikisi eşit borç, tümüyle farklı dağılımdır.
• Kodla birlikte sürümleme on ikinci sürümde 17 doğru iddia bırakır ve bayat kalan 39 iddianın 39’u sessizdir; taşımak tek başına bakım değildir.
• İnceleme borcu 43/672’ye indirir ve doğru iddiayı 41’e çıkarır, çünkü imza ile akış yüzeyindeki 38 iddiayı görür.
• Geriye kalan 15 iddia ad ve kavram yüzeyindedir, incelemede görünmez ve hepsi sessizdir; bu sayı sonraki derslerin başlangıç noktasıdır.

Sonraki Adım

İnceleme, iddiayı okuyan bir insan olduğu için çalışır ve okuyan insan pahalıdır. Yüzeylerden biri için daha ucuz bir yol vardır: iddiayı elle yazmak yerine bağlandığı kaynaktan üretmek. Üretilen bir iddia kaynağıyla birlikte değişir ve bayatlaması düşünülemez hâle gelir. Sonraki ders üretim yaklaşımlarını sınıf adlarıyla ayırır ve üretimin hangi yüzeyi gerçekten kurtardığını, hangi iki yüzeyi hiç kurtarmadığını ölçer.