--- title: 'Örnek ve Kod Parçacıkları' source: 'https://academia.sh/tr/kurslar/teknik-yazarlik/ornek-ve-kod-parcaciklari' course: 'Teknik Yazarlık ve Dokümantasyon' language: tr updated: '2026-08-17T18:10:50+00:00' license: 'CC BY-SA 4.0' --- # Örnek ve Kod Parçacıkları Çalıştırılabilir örneğe gömülü iddia bayatlayınca ses çıkarır, gömülü olmayan çıkarmaz; 56 iddianın 17'si gömülüdür ve on ikinci sürümde bayatlayan 56 iddianın 39'u sessizdir — 0,6964. Önceki ders bir ayrımı ortaya çıkardı. Terim yeniden adlandırıldığında tarama **31** iddiayı kaçırdı; bunların **8**'i ses çıkardı, **23**'ü çıkarmadı. Ses çıkaranların tek ortak özelliği vardı: çalıştırılabilir bir örneğin **içinde** duruyorlardı. Bu dersin sorusu o özelliğin adını koymak ve bedelini ölçmektir: **bir dokümanın kaç iddiası gerçekten gömülüdür, gömülülük oranı değiştirilirse sessiz bayatlama ne kadar geriler ve nerede geri çekilmeyi bırakır?** ## Gömülü İddia ile Yanındaki Cümle Bir örneğin çevresinde iki ayrı cümle türü bulunur ve ikisi bayatlama karşısında bambaşka davranır. Birincisi **örneğin kendisidir**. Örnek bir çağrının biçimini, bir alanın adını, bir adımın sırasını iddia eder; bu iddialar cümle olarak yazılmamıştır, **kod olarak** yazılmıştır. Ürün değiştiğinde örnek çalışmaz ve bu bir olaydır: sınama düşer, kurma adımı kırılır, okur bir hata iletisi alır. **Gömülü iddia**, doğruluğu çalıştırılarak sınanabilen iddiadır. İkincisi **örneğin yanına yazılmış cümledir**: "bu çağrı eşik alanını yüzde olarak alır". Aynı bilgiyi taşır, aynı şeye bağlıdır, ama hiçbir yerde sınanmaz. Ürün eşik alanını saniyeye çevirdiğinde örnek yine çalışır — sayı geçerlidir, yalnız anlamı değişmiştir — ve cümle sessizce yanlışlaşır. Ayrım bu yüzden "örnek var mı" sorusuyla ölçülmez. **Aynı iddianın örneğin içinde mi yoksa yanında mı durduğuyla ölçülür.** Yanındaki cümlelerin çoğu, örneğin içine taşınabilir: alanın birimi bir doğrulama satırıyla, dönen alanın varlığı bir yazdırmayla, sıranın önemi adımların gerçekten sırayla çalışmasıyla iddia edilebilir. ## Çalışır, Eksiksiz, Doğrulanabilir Gömülülük bir niyet değil, bir özelliktir ve üç koşulu birden ister. Üçü ayrı ayrı tanımlanır çünkü ayrı ayrı düşerler. **Çalışır:** örnek kopyalanıp çalıştırıldığında yürür. Eksik bir alma satırı, tanımsız bir değişken ya da yorum içinde bırakılmış bir seçenek örneği çalışmaz yapar. **Eksiksiz:** örnek dışarıdan hiçbir tanım beklemez. Bir önceki örnekte kurulmuş bir değişkeni kullanan parçacık, tek başına kopyalandığında düşer; okur çoğunlukla tek başına kopyalar. **Doğrulanabilir:** örneğin beklenen çıktısı yanında yazılıdır ve karşılaştırılabilir. Çıktısı yazılmamış bir örnek çalışır ama **yanlış çalıştığı fark edilmez**; ses çıkarması için düşmesi gerekir, oysa çoğu bayatlama düşmeden, yalnız farklı bir sonuç vererek gelir. ```text # ornek dokuman parcasi , calistirilmamistir parçacık olarak yazılmış örnek sonuc = olcum.baslat(esik = 5) print(sonuc.ozet) Metindeki cümle: "baslat çağrısı esik alanını yüzde olarak alır." eksiksiz örneğe dönüşmesi için gereken satırlar - olcum'un nereden geldiği - baslat çağrılabilsin diye kurulması gereken bağlam - ozet alanının gerçekten döndüğünün yazdırılması - beklenen çıktının örneğin yanında durması ``` Üstteki parçacık üç koşulun üçünü de karşılamaz. Çalışmaz, çünkü ilk ad tanımsızdır. Eksiksiz değildir, çünkü bağlamı başka bir yerdedir. Doğrulanabilir değildir, çünkü ne yazdıracağı yazılı değildir. **Böyle bir parçacık gömülü görünür ama gömülü değildir:** bayatladığında ses çıkarmaz, çünkü zaten çalışmıyordur. ## Bu Dersin Kendi Örneği Bu ders "çalışır, eksiksiz ve doğrulanabilir örnek" diyorsa kendi örneği de öyle olmak zorundadır; yoksa dersin kendisi yukarıdaki parçacığın durumuna düşer. Aşağıdaki ölçüm bloğu bu üç koşulu karşılar. Dışarıdan hiçbir tanım beklemez: türler, yüzeyler, sıklıklar ve gömülülük oranları bloğun içindedir. Kopyalanıp çalıştırıldığında yürür. Ardından gelen etiketsiz blok, bu bloğun **gerçekten alınmış çıktısıdır**; elle yazılmamıştır ve karşılaştırılabilir. Dersin bütün sayı iddiaları o çıktıdan gelir; hiçbiri metinden gelmez. Ölçümün varsayımları: - **YD31** — 56 iddia ortak kurgudan gelir: dört tür, dört yüzey. 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. - **YD32** — Bir iddia, bağlandığı yüzey o sürüme kadar en az bir kez değiştiyse bayattır. Yüzey sıklıkları değişmez: imza **2**, akış **3**, ad **5**, kavram **12** sürümde bir. - **YD33** — Gömülü bir iddia bayatlayınca **ses çıkarır**; gömülü olmayan bayatlayınca hiçbir şey olmaz ve **sessiz** sayılır. - **YD34** — **Kavram yüzeyine bağlı iddia hiçbir örneğe gömülemez.** Bir örnek bir şeyin neden öyle olduğunu çalıştırarak iddia edemez; yalnız nasıl davrandığını iddia edebilir. - **YD35** — Bu dersin değiştirdiği tek şey **gömülülük oranıdır**. Türlerin yüzey dağılımı ve yüzeylerin sıklığı ortak tanımdaki gibidir. - **YD36** — Üç gömülülük rejimi denenir: **parçacık** (oranlar yarıya iner; eksik yazılmış örnek gömülü sayılmaz), **ortak tanım** (kurgunun kendi oranları), **tam örnek** (her tür örneklerini eksiksiz yazar, referans da örnek taşır). - **YD37** — Sessizlik oranı bayatlayanlar üzerinden hesaplanır; hiçbir iddianın bayat olmadığı sürümlerde oran tanımsızdır. ## Ölçüm ```python """Ornek ve kod parcaciklari: gomulu iddia ses cikarir, gomulu olmayan cikarmaz. Bolum 1 - gomulu iddialarin turlere dagilimi. Bolum 2 - surum surum dogru/bayat/sessiz ve sessizin bayata orani. Bolum 3 - bu dersin degistirdigi tek sey: gomululuk orani. """ TOHUM = 20260816 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} SURUMLER = (0, 1, 2, 3, 6, 12) # Bu dersin değiştirdiği tek şey: gömülülük oranı. Yüzeyler ve türler sabit. REJIM = { "parçacık": {t: o / 2 for t, o in ORNEKLI.items()}, "ortak tanım": ORNEKLI, "tam örnek": {"öğretici": 0.80, "nasıl yapılır": 0.85, "açıklama": 0.40, "referans": 0.60}, } def iddialar(oranlar=ORNEKLI): """Her iddia: türü, bağlandığı yüzey, çalıştırılabilir örneğe gömülü mü.""" liste, no = [], 0 for tur, dagilim in TURLER.items(): hedef = 0 for yuzey, adet in dagilim.items(): for _ in range(adet): no += 1 hedef += oranlar[tur] gomulu = hedef >= 1 and yuzey != "kavram" if gomulu: hedef -= 1 liste.append({"no": no, "tur": tur, "yuzey": yuzey, "gomulu": gomulu}) return liste def bayat_mi(i, surum): return surum // SIKLIK[i["yuzey"]] >= 1 def olc(liste, surum): """Doğru kalan, bayatlayan ve bayatlayanın sessiz olanı.""" bayat = [i for i in liste if bayat_mi(i, surum)] sessiz = [i for i in bayat if not i["gomulu"]] return len(liste) - len(bayat), len(bayat), len(sessiz) A = iddialar() print(f"iddia {len(A)}, tür {len(TURLER)}, " f"örneğe gömülü {sum(1 for i in A if i['gomulu'])}") print("gömülü dağılımı: " + ", ".join( f"{t} {sum(i['gomulu'] for i in A if i['tur'] == t)}" for t in TURLER)) print() print(f"{'sürüm':>6s} {'doğru':>6s} {'bayat':>6s} {'sessiz':>7s} {'sessiz/bayat':>13s}") for s in SURUMLER: dogru, bayat, sessiz = olc(A, s) oran = f"{sessiz / bayat:.4f}" if bayat else "-" print(f"{s:6d} {dogru:6d} {bayat:6d} {sessiz:7d} {oran:>13s}") print() print(f"{'gömülülük rejimi':>17s} {'gömülü':>7s} {'sürüm 12 bayat':>15s}" f" {'sessiz':>7s} {'sessiz/bayat':>13s}") for ad, oranlar in REJIM.items(): liste = iddialar(oranlar) dogru, bayat, sessiz = olc(liste, 12) print(f"{ad:>17s} {sum(1 for i in liste if i['gomulu']):7d} {bayat:15d}" f" {sessiz:7d} {sessiz / bayat:13.4f}") print() print(f"{'tür':>15s} {'gömülü':>7s} {'sürüm 3 sessiz':>15s} {'sürüm 12 sessiz':>16s}") for t in TURLER: grup = [i for i in A if i["tur"] == t] print(f"{t:>15s} {sum(i['gomulu'] for i in grup):7d}" f" {olc(grup, 3)[2]:15d} {olc(grup, 12)[2]:16d}") ``` ``` iddia 56, tür 4, örneğe gömülü 17 gömülü dağılımı: öğretici 8, nasıl yapılır 9, açıklama 0, referans 0 sürüm doğru bayat sessiz sessiz/bayat 0 56 0 0 - 1 56 0 0 - 2 34 22 17 0.7727 3 18 38 24 0.6316 6 11 45 28 0.6222 12 0 56 39 0.6964 gömülülük rejimi gömülü sürüm 12 bayat sessiz sessiz/bayat parçacık 8 56 48 0.8571 ortak tanım 17 56 39 0.6964 tam örnek 31 56 25 0.4464 tür gömülü sürüm 3 sessiz sürüm 12 sessiz öğretici 8 5 7 nasıl yapılır 9 4 5 açıklama 0 2 12 referans 0 13 15 ``` ## Bayatlamanın Çoğu Sessizdir İlk tablo kursun üçüncü iddiasını ödüyor. On ikinci sürümde 56 iddianın **56**'sı bayattır ve bunun **39**'u sessizdir: **0,6964**. Dokümanın üçte ikisi yanlıştır ve yanlış olduğunu kimseye söylememektedir. Sayı yalnız son satırda büyük değil. İkinci sürümde bayatlayan 22 iddianın **17**'si sessizdir — oran **0,7727** ile en yüksek noktasındadır. Bunun nedeni ilk bayatlayan yüzeyin **imza** olması ve imza iddialarının büyük bölümünün referansta durmasıdır; referansın gömülü iddiası yoktur. **Dokümanın en erken bayatlayan bölümü, aynı zamanda en sessiz bölümüdür.** Oran üçüncü ve altıncı sürümde **0,6316** ve **0,6222**'ye iner. Bu düşüş bir iyileşme değil: akış yüzeyi devreye girer, akış iddialarının çoğu öğretici ile nasıl yapılırdadır ve o iki tür gömülü örnek taşır. Yani ses çıkaran iddialar bu aralıkta bayatlar. On ikinci sürümde kavram yüzeyi de düşünce oran yeniden yükselir, çünkü kavram iddiaları hiçbir zaman gömülü olamaz. Bu oranın pratik anlamı bir yanılsamadır. Bir ekip dokümanının sağlığını "ne kırıldı" sorusuyla izliyorsa, on ikinci sürümde eline **17** bildirim geçer ve bunların hepsini düzeltir. Düzeltme bittiğinde dokümanın hatasız olduğuna inanır. Gerçek sayı ise **56** bayat iddiadır; görülmeyen **39**'u yerinde durmaktadır. **Ses çıkaran bayatlamayı düzeltmek, sessiz bayatlamayı görünmez olmaktan çıkarmaz; tersine, dokümanı sağlıklı gösteren bir kanıt üretir.** Bu kümede ölçülebilen en küçük fark **1/56 = 0,0179**'dur. Rejimler arasındaki farklar bunun kat kat üstündedir ve karşılaştırılabilir; 0,6316 ile 0,6222 arasındaki fark ise tek bir iddiadan küçüktür ve bir eğilim olarak okunmamalıdır. ## Gömülülüğü Yükseltmek İkinci tablo dersin değiştirdiği tek şeyi gösteriyor. Aynı 56 iddia, aynı yüzeyler, aynı sıklıklar; değişen yalnız kaç iddianın çalıştırılabilir örneğe gömüldüğü. **Parçacık** rejiminde gömülü iddia **8**'e düşüyor ve sessizlik **0,8571**'e çıkıyor. Bu rejim örneği olmayan bir dokümanı anlatmıyor; **örneği olan ama eksiksiz olmayan** bir dokümanı anlatıyor. Yarım yazılmış örnek sayfada durur, okura bir şey gösterir ve bayatladığında hiçbir şey söylemez. **Tam örnek** rejiminde gömülü iddia **31**'e çıkıyor, sessizlik **0,4464**'e iniyor. Sessiz iddia sayısı 39'dan **25**'e düşüyor: on dört iddia sessiz olmaktan çıkıp ses çıkaran sınıfa geçiyor. Referansın da çalıştırılabilir örnek taşıması bu farkın büyük bölümünü üretiyor. Tablo aynı zamanda bir tabanı gösteriyor: sessizlik **sıfırlanmıyor**. En yüksek oranlarda bile 25 iddia sessiz kalıyor, çünkü **kavram yüzeyine bağlı iddialar hiçbir örneğe gömülemez**. Bir örnek bir şeyin nasıl davrandığını çalıştırarak iddia edebilir; **neden öyle olduğunu** iddia edemez. Gömülülük bir bakım aracıdır ve erişemediği bir bölge vardır; o bölge için doküman denetiminden başka yol yoktur. ## Kopya Gömülü Değildir Tablo bir şeyi sormuyor: bir iddiayı gömülü yapan tam olarak nedir? Sayfadaki kod bloğu kendi başına metindir; hiçbir metin bayatladığını kendi kendine bildirmez. Ses çıkaran şey **aynı metnin bir yerde gerçekten çalıştırılmasıdır**. Bunun iki yolu vardır. Birincisi dokümandaki örneğin **kendisinin** çalıştırılmasıdır — bu dersteki ölçüm bloğu gibi. İkincisi örneğin, çalıştırılan bir kaynaktan **alınmasıdır**; doküman kodu barındırmaz, gösterir. Üçüncü bir durum vardır ve en aldatıcı olan odur: **kopya**. Ekip örnekleri sınanan bir yerde tutar, dokümana da onların bir kopyasını yapıştırır. Kaynak sınanır, doğru kalır ve herkes örneklerin sınandığını sanır. Oysa sınanan kopya değildir; ürün değiştiğinde kaynak düzeltilir, doküman düzeltilmez ve iki metin sessizce ayrışır. Kopyalanmış örnek ölçümde **gömülü sayılmaz**; dokümanı doğrudan üstteki **parçacık** sütununa taşır ve sessizliği **0,8571**'e çıkarır. Kopyanın maliyeti, örneksizliğin maliyetinden büyüktür: örneği olmayan doküman kimseyi yanıltmaz, kopyalı doküman hem okuru hem yazanı yanıltır. Bu ölçütün ikinci sonucu örneğin **boyutudur**. Eksiksizlik koşulu örneği uzatır; önceki dersin ölçtüğü taranabilirlik ise uzunluğu cezalandırır — okur her satırı bir adım olarak öder. İki koşul gerçekten çekişir ve çözüm ortada bir yerde değildir. Doğru ayar **en küçük eksiksiz örnektir**: gerçek kullanımın tamamını değil, iddiayı taşıyan en kısa çalışır bütünü yazmak. Örnekten çıkarılan her satır bir iddiayı gömülü olmaktan çıkarır; bu yüzden çıkarma kararı estetik değil, ölçülebilir bir karardır — hangi iddiadan ses almaktan vazgeçiliyor? Örneğin kaynakla birlikte sürümlenmesi ve inceleme sürecine girmesi bu konunun işi değildir; kursun son konusu doküman işletimini ayrıca kurar. Burada ölçülen yalnız şudur: bir iddia, ancak onu taşıyan metin gerçekten çalıştırılıyorsa ses çıkarır. ## Sessizliğin Tür Dağılımı Son tablo dört türü sessizlik açısından karşılaştırıyor ve bir tersliği açığa vuruyor. **Açıklama** en uzun yaşayan türdür — üçüncü sürümde yalnız **2** sessiz iddiası vardır. On ikinci sürümde ise **12** iddiasının **12**'si sessiz bayattır: tür bütünüyle, tek bir uyarı üretmeden yanlışlaşır. **Referans** tersini yapar: üçüncü sürümde zaten **13** sessiz iddia taşır ve on ikinci sürümde **15**'e çıkar. Hızlı bayatlar ve baştan sona sessizdir. Öğretici ile nasıl yapılır ise sırasıyla **7** ve **5** sessiz iddiayla en iyi durumdadır; ikisi birlikte 17 gömülü iddianın tamamını taşır. Sonuç yazma önceliğini belirler. En çok örnek taşıyan iki tür zaten en çok ses çıkaran türlerdir; oraya bir örnek daha eklemenin kazancı sınırlıdır. Kazanç, **hiç örneği olmayan türlerdedir**: referansın 15 iddiası ile açıklamanın 12 iddiası, ürünün geri kalanının tümünden daha sessizdir. ## Özet - Gömülü iddia örneğin **içinde** durur ve çalıştırılarak sınanır; örneğin **yanına** yazılmış cümle aynı bilgiyi taşır ama sınanmaz ve sessizce yanlışlaşır. - Örnek üç koşulu birden ister: **çalışır**, **eksiksiz**, **doğrulanabilir**. Üçünden biri düşerse örnek gömülü görünür ama gömülü değildir. Bu dersin kendi ölçüm bloğu üç koşulu da karşılar ve çıktısı gerçekten alınmıştır. - On ikinci sürümde 56 iddianın **56**'sı bayat, **39**'u sessizdir: **0,6964**. En yüksek sessizlik ikinci sürümdedir (**0,7727**), çünkü ilk bayatlayan yüzey imzadır ve imza iddialarının çoğu örneksiz referanstadır. - Gömülülük oranı değiştiğinde sessizlik **0,8571** ile **0,4464** arasında hareket eder; yarım yazılmış örnek gömülülüğü 17'den **8**'e düşürür, eksiksiz örnek **31**'e çıkarır. - Sessizlik sıfırlanamaz: kavram yüzeyine bağlı iddialar hiçbir örneğe gömülemez. En sessiz iki tür açıklama (**12/12**) ve referanstır (**15**); örnek eklemenin kazancı oradadır. ## Sonraki Adım Örnek, dokümanda kendi kendini sınayabilen tek öğedir. Metnin yanında duran ikinci bir öğe daha vardır ve o hiçbir koşulda çalıştırılamaz: **diyagram**. Diyagram da iddia taşır — bir bileşenin adını, bir akışın sırasını, bir kavramın yapısını — ve taşıdığı iddialar tıpkı cümleler gibi bir yüzeye bağlanır. Sonraki ders diyagramın hangi yüzeye bağlandığını, bu seçimin bayatlama hızını nasıl belirlediğini ve görsel bayatlamasının neden istisnasız sessiz olduğunu ölçer.