yazılım-tasarımı-felsefesi

SKILL.md

---
name: yazılım-tasarımı-felsefesi
description: Değişiklik, dışa aktarılmış veya içe aktarılabilir bir isim eklediğinde, bir modül, sınıf, bileşen, yardımcı, hook, servis veya sarmalayıcı oluşturduğunda, tekrarlanan kodu merkezileştirdiğinde veya bir API değiştirdiğinde kod yazarken, değiştirirken veya incelerken kullanın. Ousterhout kuralları (derin modüller, bilgi gizleme, karmaşıklığı aşağı çekme) artı kod paylaşımı için değişmez test, okuyucu maliyeti testi ve sonunda gerekli bir tasarım notu içerir.
---

# A Philosophy of Software Design (John Ousterhout)

## Bu beceriyi ne zaman kullanmalı

Bu beceriyi kod tasarlarken, yazarken, değiştirirken veya incelerken kullanın. Modül tasarımı, API değişiklikleri, parçalama, yeniden düzenleme, isimlendirme, yorumlar, testler ve performans çalışmaları için geçerlidir. Ayrıca bir değişiklik garip hissettirdiğinde veya bir değişiklik birçok dosyaya yayıldığında da kullanın.

## Düzeltilecek önyargı

Çalışan kod, basit kodla aynı şey değildir. Küçük parçalar, tanıdık kalıplar, bayraklar, sarmalayıcılar ve ekstra dokümantasyon bir tasarımı daha karmaşık hale getirebilir. Bunu, okuyucunun bilmesi gerekenlere ek yaptıklarında veya bilgiyi diğer modüllere sızdırdıklarında yaparlar.

## Karar kuralları

- Bir tasarımı karmaşıklığı ne kadar azalttığına göre ölçün. Okuyucunun yükünü azaltan tasarımı tercih edin. Karmaşıklığın dört işareti vardır. Bir değişiklik birçok yerde düzenleme gerektirir. Bağımlılıklar gizlidir. Adımlar sabit bir sırayla gerçekleşmelidir. Okuyucu birçok gerçeği aklında tutmak zorundadır.
- Tasarımı sürekli bir çalışma olarak ele alın. Çalışan ilk yama, sonraki değişiklikleri zorlaştırıyorsa bitmiş sayılmaz. Bir arayüz, modül bölünmesi veya soyutlama hakkında karar verirken iki veya daha fazla olası tasarımı karşılaştırın.
- Derin modülleri tercih edin. Derin bir modül küçük bir arayüze sahiptir ve büyük miktarda karmaşıklığı gizler. Geçiş hizmetlerini, ince kütüphane sarmalayıcılarını ve küçük yardımcı modülleri reddedin. Okuyucunun yükünü azaltmayan, sadece isim ekleyen herhangi bir çıkarımı reddedin.
- Bir arayüzü, çağıranın bilmesi gerekenler etrafında tasarlayın, uygulamanın nasıl çalıştığı etrafında değil. Kırılgan kurulum dizilerini, mod bayraklarını, yapılandırma düğmelerini ve iç seçimleri gösteren argümanları kaçının.
- Değişebilecek kararları gizleyin. Örnekler: dahili temsiller, depolama şekli, protokoller, dosya formatları ve performans hileleri. Muhasebe, normalleştirme ve uç durumlar diğer örneklerdir. Her birini bilgiyi sahiplenen modülün içinde tutun.
- Karmaşıklığı, detayı sahiplenen modüle çekin. Çağıranlara daha basit bir sözleşme sunan ve her çağrı noktasından tekrarlanan işi kaldıran daha karmaşık bir uygulamayı kabul edin.
- Bir modülü doğru seviyede genel yapın. Bir modülü tek bir çağırana uydurmayın. Gelecekteki ihtiyaçlar için belirsiz bir soyutlama eklemeyin. Nadir uç durumları ana yoldan uzak tutun ve özel davranışı kendi yerine koyun.
- Modülleri toplam karmaşıklığa göre birleştirin veya bölün. Boyuta, kodun çalıştırılma sırasına, alışkanlığa veya görünüme göre birleştirmeyin veya bölmeyin. İlgili durumu, davranışı, kuralları ve kararları birlikte tutun. Yeni sınır daha derin ve okuyucu her iki tarafı da tek başına anlayabiliyorsa bölün.
- İstisnalar kümesini küçültün. Mümkünse, arayüzü veya kuralları değiştirerek geçersiz durumların oluşmasını engelleyin. Her çağıranın aynı savunma kodunu tekrarlamasına izin vermeyin.
- Yorumları karmaşıklığı azaltmak için kullanın. Arayüz sözleşmelerini, geçerli kalması gereken kuralları, gizli tasarım kararlarını ve nedenlerini yazın. Ayrıca çağıranların bilmemesi gereken zor gerçekleri yazın. Kodu yorumda tekrarlamayın. Kötü bir ismi, kötü bir bölünmeyi veya kafa karıştırıcı kontrol akışını gizlemek için yorum kullanmayın.
- İsimleri, tutarlılığı ve açıklığı tasarım bilgisi olarak ele alın. Bir isim okuyucuya soyutlamayı anlatır, mekanizmayı değil. İlgili işlemler aynı konvansiyonları kullanır. Okuyucuyu şaşırtan kod, kısa olsa bile karmaşıklık ekler.
- Testleri genel sözleşmeler ve stabil API'lere karşı yazın. Gizli karmaşıklığı ve özel durumları bu sözleşmeler aracılığıyla test edin. Testin kolaylığı yüzünden sığ veya sızdıran bir arayüze izin vermeyin.
- Performans değişikliği, bir kalıp, paradigma veya çerçeve ekleyin ancak iki nedenden biri için: Bu kod tabanındaki karmaşıklığı azaltır veya kanıtlar bu ödünleşmenin gerekli olduğunu gösterir. Her optimizasyonu stabil bir arayüzün arkasına gizleyin.

## İşaretler ve her birine yanıt

- Bir özellik garip, bir değişiklik dosyalara yayılmış veya bir inceleyen gizli bağımlılıkları bulmak zorunda. Yanıt: eksik bilgi gizleme ve sığ modüller arayın. Ayrıca sabit sıradaki adımları ve çağıranların taşıdığı karmaşıklığı arayın.
- Bir modül, katman, servis, yardımcı, sarmalayıcı veya cephe ekliyorsunuz. Ya da bir kalıp, seçenek, geri çağırma veya argüman ekliyorsunuz. Yanıt: eklediğinden daha fazla karmaşıklığı gizlediğini gösterin.
- Bir API değiştiriyorsunuz. Yanıt: normal bir çağıranın ne bilmesi gerektiğini kontrol edin. Bir çağıranın çağrı sırasını, temsili veya depolamayı bilmesi gerekmez. Bir çağıranın taşıma, önbellek, protokol veya dosya formatını bilmesi gerekmez. Bir çağıranın iç iş akışını veya birçok kurulum adımını bilmesi gerekmez.
- Özel bir durum, bayrak, istisna yolu, koşul veya çağıranların görebileceği bir konteyner ekliyorsunuz. Yanıt: önce sahip olan modülün ne yapabileceğini sorun. Geçersiz durumu kaldırabilir, alışılmadık davranışı izole edebilir veya daha güçlü bir işlem verebilir.
- Kodu bölüyorsunuz, bir fonksiyon çıkarıyorsunuz veya bir değişken ekliyorsunuz. Yanıt: yeni sınırın veya ismin anlam taşıdığını kontrol edin. Sadece atlamalar, geçen durum veya çağıranların görebileceği ara adımlar eklememelidir.
- Kodda `prepare`, `process` ve `finalize` gibi aşamalar var veya çağıranlar nesneleri aşamalı olarak oluşturmak zorunda. Yanıt: zaman sırasının gerçek kavram olup olmadığını kontrol edin. Değilse, kodu stabil sorumluluklar etrafında organize edin.
- Bir isim belirsiz, bir mekanizmayı adlandırıyor, tutarlı değil veya okuyucuyu şaşırtıyor. Yanıt: soyutlama sınırı hakkında tekrar düşünün. Neredeyse doğru olan bir ismi kabul etmeyin.
- Bir yorum uzun, kodu tekrarlıyor, kafa karıştırıcı bir arayüzü açıklıyor veya kullanımı açıklamak için iç detayları gösteriyor. Yanıt: soyutlamayı değiştirin veya eksik sözleşmeyi arayüze taşıyın.
- Performansı optimize ediyorsunuz. Yanıt: önce ölçün, sonra optimizasyonu gizleyin. Ödünleşmenin gerekli olduğuna dair kanıt olmadan modül derinliğinden veya bilgi gizlemeden vazgeçmeyin.
- Test yapıyor veya inceleme yapıyorsunuz. Yanıt: genel davranışa ve arayüz sözleşmelerine bakın. Ayrıca stabil API'lerin arkasındaki gizli karmaşıklığa ve soyutlama arkasında tutulan özel durumlara bakın.

## Son kontrol listesi

- Değişiklik, sistemi anlamak, değiştirmek, doğrulamak ve genişletmek için gereken çabayı azaltıyor mu?
- Her arayüz öğesi, sarmalayıcı, katman, yardımcı, seçenek ve isim, karmaşıklığı gizlemek için yeterince gerekçelendiriliyor mu?
- Önemli kararlar tek bir yerde mi? Bağımlılıklar görünür mü? Çağıranların bilmesi gereken kısıtlamalar yazılı mı? Değişebilecek iç detaylar korunuyor mu?
- Yaygın durumlar ekstra adımlar olmadan çalışıyor mu? Nadir kontroller, özel durumlar, performans hileleri ve istisna detayları yaygın yoldan uzak mı duruyor?
- İsimler tam ve tutarlı mı? Yorumlar güncel mi, kodun tekrarı yok mu? Kod mevcut konvansiyonlara uyuyor mu, yeni bilgi olmadıkça değiştirilmemiş mi?

## Kapı

Değişiklik, başka kodun dışa aktarabileceği veya içe aktarabileceği bir isim ekliyorsa tam kontrol listesini kullanın. Ayrıca değişiklik bir modül, sınıf, bileşen, yardımcı, hook, servis veya sarmalayıcı oluşturduğunda ya da tekrarlanan kodu tek bir yere koyduğunda kullanın. Yeniden adlandırmalar, kod modları, yapılandırma değişiklikleri, veri değişiklikleri ve tek satırlık düzeltmeler buna gerek duymaz.

## Değişmezlik testi: sadece birlikte değişen kodu paylaş

- Paylaşılan kodu ancak adlandırabileceğiniz bir kuralı koruyorsa çıkarın. Kanıt, birlikte değişimdir: geçmiş, kopyaların birlikte düzeltildiğini veya değiştirildiğini gösterir. Sadece benzer görünen ve bağımsız değişen kodlar uyak gibidir. Uyakları çoğaltılmış olarak bırakın. Üç benzer blok bir kuralı kanıtlamaz.
- Bir düzeltme problemi kaldırmalı, sadece yerini değiştirmemeli. Altı dönüşümün tek bir genel dönüşüm yardımcısına taşınması hâlâ altı dönüşümdür. Dönüşümlerin gizlediği tipli eşleyiciyi yazın.
- Bir soyutlama yanlışsa, kodu tekrar satır içine koyun ve çoğaltmanın geri dönmesine izin verin. Soyutlamayı bayraklarla zorlamayın.
- Kodun sadece boyutu nedeniyle bölünmesine izin vermeyin. Tek bir 400 satırlık modül, tek bir kararı gizliyorsa, aynı birleşimleri sızdıran dört 100 satırlık modülden iyidir.
- Clean Code veya SOLID'in mekanik okunması (çok küçük fonksiyonlar, her sorumluluk için bir sınıf) sığ modüller verir. Bu beceri, o baskının önündedir.

## Okuyucu maliyeti: üçüncü test

Derinlik testi ve değişmezlik testi bir sınırın var olup olmayacağını belirler. Okuyucu maliyeti testi, sınır çevresindeki kodun değiştirilmesinin ucuz olup olmadığını belirler. Sonraki okuyucu, kişi veya ajan, okumak zorunda olduğu her satır için ödeme yapar. Bir ajan token ile öder. Bir ajan kodu metin araması, kısmi okuma, tip kontrolü ve testlerle bulur.

- **Bulunabilir.** Her kavram için bir isim kullanın. Her yerde aynı şekilde yazın, böylece düz metin araması bulur. Kusurlar: dizelerden oluşturulan isimler, import yan etkileriyle bağlantı, bir kavram için iki isim. Tanımı gizleyen yeniden dışa aktarma zincirleri de kusurdur.
- **Erken durma.** Sözleşmeyi dosyanın en üstüne veya dışa aktarımın üstüne koyun. Ne vaat ettiğini, neyi gizlediğini ve asla ne yapmadığını söyleyin. Böylece okuyucu erken durabilir.
- **Makine tarafından kontrol edilebilir.** Her sınırın içine ve dışına kesin tipler kullanın, böylece tip kontrolü çağıranları okumayı yerine geçer. Kusurlar: `any`, düz sözlükler, anlamı sadece gövdede olan boolean bayraklar.
- **Görünür bağlılık.** İki yer birlikte değişmeli. Bunu paylaşılan bir tip, test veya tek kaynakla zorlayın. Yapamıyorsanız, her iki yerde işaretleyin.
- **Gürültü yok.** Kodu tekrarlayan yorumları ve yorum satırına alınmış kodu kaldırın. Ölü dalları ve değişim geçmişini kaydeden yorumları kaldırın. Yerini alan eski yolu yanına bırakmayın.
- **Öngörülebilir.** Depo mevcut düzenine uyun. Testi okuyucunun aradığı yere koyun ve tek başına çalıştırın.

Dosya boyutu bu listede kasıtlı olarak yoktur. Çok büyük bir dosya, ikinci gizli karar aramak için bir nedendir. Dosyayı kesmek için asla bir neden değildir.

## Güvenlik

Mevcut kod için önce mevcut davranışı tutan bir test yazın. Sonra modülü derinleştirin. Yeni kod için, amaçlanan davranışı tanımlayan testi yazın.

## Tasarım notu (kapı geçerli olduğunda zorunlu)

Kapı geçerliyse, çekme isteği açıklamasında `## Design note` başlıklı bir bölüm koyun. İki ila dört satır yazın:

- Eklediğiniz her sınır ve gizlediği karar.
- Bilerek tuttuğunuz her çoğaltma ve nedeni.
- Kabul ettiğiniz her sığ kısım ve nedeni.

Kapı geçerli değilse, `## Design note` yazıp ardından `Gate not applicable: <sebep>` yazın. Tasarım notunu son adımınızın özetine de koyun.

## İnceleme modu

Başka bir ajan veya kişinin yazdığı kodu incelerken veya test ederken bu bölümü kullanın.

1. Tasarım notunu kontrol edin. Kapı geçerliyse ve çekme isteğinde `## Design note` bölümü yoksa, engelleyici bir bulgu bildirin. Not diff ile uyuşmuyorsa, engelleyici bulgu bildirin.
2. Bir tasarım bulgusu ancak iki koşulu sağladığında engelleyicidir:
   - Bu becerinin bir kuralını adlandırır. Kural, karar kuralı, kapı, değişmezlik testi veya bir okuyucu maliyeti maddesidir.
   - Okuyucuya veya sonraki değişime somut bir maliyet belirtir. Örnekler: "Çağıranlar depolama şeklinin farkında olmalı." "Bir kavramın iki ismi var." "Bir kap değişikliği üç dosyada düzenleme gerektirir."
3. Diğer tüm tasarım gözlemlerini engelleyici olmayan olarak işaretleyin. Bunları "Engelleyici olmayan tasarım notları" başlıklı ayrı bir listeye koyun. Engelleyici olmayan notlar işi yapana geri göndermez.
4. Tercihleri bulgu olarak bildirmeyin. Farklı isim, dosya düzeni veya stil tercihtir. Sadece adlandırılmış bir kuralı kırarsa ve somut maliyeti varsa bulgu olur.
5. Aynı tasarım bulgusu ikinci inceleme döngüsünde tekrar gelirse, yükseltin. Aynı değişikliği üçüncü kez istemeyin.

## İlgili beceriler (yüklendiğinde)

- `find-shared-code`: paylaşmaya değer kod için son geçmişte rapor amaçlı arama. Bu becerinin değişmezlik testi ve derinlik testini kullanır.
- `refactoring` ve `working-effectively-with-legacy-code`: daha derin tasarıma güvenli adımlar. Bu beceri yeni sınırın kalıp kalmayacağını belirler.

## Kaynak ve lisans

Bu beceri, GitHub'daki ciembor/agent-rules-books deposunda bulunan A Philosophy of Software Design için "mini" kurallar üzerine inşa edilmiştir (MIT lisansı, commit 893a88a). Kapı, değişmezlik testi, okuyucu maliyeti testi, tasarım notu ve inceleme modu bu kurallara eklemelerdir. Depo ayrıca kitabın tam kurallarını da içerir.

Etiketler