--- title: 'Katkı Rehberleri' source: 'https://academia.sh/tr/kurslar/kod-inceleme/katki-rehberleri' course: 'Kod İnceleme ve Ekip Süreci' language: tr updated: '2026-08-17T18:10:46+00:00' license: 'CC BY-SA 4.0' --- # Katkı Rehberleri Yazılı beklenti incelemeden önce çalışır: dar bir incelemede rehberin kapsamı büyüdükçe tur 6'dan 5, 4, 3 ve 2'ye iner, geniş incelemede tur 2'de sabit kalır, ve gereksinim beyanı isteyen rehber kaçan 24'lük kümede ilk kez 0'a düşürür. Ö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. ```text # ö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 ```python """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?