Neden tasarım dokümanları yerine throwaway code’u tercih ediyorum

• Yazılım geliştirmede tasarım dokümanından doğrudan temiz bir PR’a geçmek zordur; çünkü gerçek kodlama sırasında varsayımlar sarsılır ve tasarımı atılacak kod üzerinden keşfetmek daha hızlı olabilir
• Birleştirilmesi planlanmayan bir draft PR içinde prototip veya kavram kanıtı oluşturup, erken aşamada review alarak yaklaşımın yönünü hizalama ve ardından bunu tasarım fikrinin kaydı olarak bırakma akışı öneriliyor
• Bu yaklaşımın ön koşulu, ilk çözümü cesurca çöpe atabilecek kurumsal olgunluk; aynı problemi 2-3 farklı şekilde uygulamaya koyabilme rahatlığı ise kıdemin bir göstergesi sayılıyor
• PR’lar, belirli bir andaki uygulama niyetini ve tartışmayı barındıran keşfedilebilir dokümanlar haline gelebilir; buna karşılık tasarım dokümanları sık güncellenmezse gerçeklikten kopan birer “undead documentation” olmaya yatkındır
• Yine de tasarım dokümanları; farklı paydaşlardan gelen geri bildirimleri derlemek, uzun vadeli bir North Star dokümanı oluşturmak, henüz kodlanması zor erken fikirleri ele almak veya prototipin doğrudan production’a çıkma riski olan organizasyonlarda hâlâ gereklidir

---

Throwaway PR ile tasarımı keşfetmek

• İdeal geliştirme akışı; bir tasarım dokümanı yazmak, küçük PR’ları sırayla merge ederek özelliği yayımlamak ve Git geçmişini temiz tutmak gibi görünür
• Gerçekte ise çoğu zaman ancak kodlamaya başladıktan sonra tasarım dokümanındaki varsayımlar sarsılır ve neyi hangi sırayla yayımlamak gerektiğine yeniden karar vermek gerekir
• Bu yüzden önce büyük bir kod deneyi oluşturup, gerçek planı onun sonuçlarına göre kurmak daha verimli olabilir

• Önerilen süreç

  • Merge etme niyeti olmayan bir draft PR içinde prototip veya kavram kanıtı geliştirin
  • Büyük refactor’lar veya bir özelliğe yaklaşım biçimi hakkında erken aşamada başkalarının bakışını alarak yön hizalaması sağlayın
  • Yaklaşımı draft PR içinde dokümante ederek tasarım fikrinin tarihsel kaydı olarak bırakın
  • Mümkün olan en erken anda draft PR’ın tamamını atmaya hazır olun
  • Draft PR içinden gerçekten dağıtıma uygun PR’ları kademeli olarak çıkarın; bunları yaklaşık bir hafta içinde temiz, dağıtım amaçlı PR’lara bölün
  • Her PR’ı aşamalara ayırırken test ve sağlamlık açıklarını kademeli olarak kapatın

• Bu yaklaşımın ekipten bekledikleri

  • En önemli koşul, kendi yazdığınız ilk fikri çöpe atabilecek olgunluğa sahip olmaktır
  • Aynı problemi 2-3 farklı şekilde kodlayabilme rahatlığı, kıdemin önemli bir işareti sayılabilir
  • Değer üretimi, production’a giren kod satırı sayısında değil; organizasyonun edindiği bilgidedir
  • Kritik noktalarda erken hizalama sağlanırsa sonrasındaki prototipleme basit bir israf olarak kalmaz
  • Kod tabanının çekirdek kısımlarını hızlıca birbirine bağlayabilecek kadar aşinalık gerekir; kıdemli çalışanlardan beklenen rahatlık düzeyi budur
  • Bu yaklaşım yalnızca bireysel değil, ekip düzeyinde de uygulanabilir

PR dokümantasyonu ve tasarım dokümanlarının gerçek rolü

• PR’lar, geliştiriciler için yararlı doküman biçimlerinden biridir
  • Belirli bir uygulamanın neden o şekilde yapıldığını anlamaya çalışırken bakılan ilk yerlerden biri olabilir
  • Güncel durumu yansıttığını iddia etmez; bunun yerine belirli bir zamandaki durumu taşıyan tarihsel bir çıktı olarak kalır
• Tasarım dokümanları, sık sık güncel tutulmazsa eski gerçekliği yansıtan undead documentation haline gelmeye yatkındır
• Prototipler, “anlatmaktan çok göstermek” yaklaşımına daha uygundur ve değişim yaratırken dokümandan çok kod daha etkili olabilir
• Ancak disiplinsiz organizasyonlarda prototipin bir “soru” değil “cevap” olarak kabul edilme riski vardır
  • Asıl niyet, “Bunu mu yapmalıyız, yoksa başka bir şey mi?” sorusuna daha yakındır
  • Organizasyon bunu “Bunu yapmalıyız” diye anlarsa sorun çıkar

• Tasarım dokümanlarının hâlâ doğru tercih olduğu durumlar

  • Farklı paydaşlardan, yöneticilerden ve dış ekiplerden gelen geri bildirimlerin derlenip saklanması gerektiğinde yararlıdır
  • Yalnızca GitHub ile böyle bir iş birliğini yürütmek zor olabilir
  • Fikir fazla kavramsal ve uzun vadeliyse, hemen kodlamak zorsa bir miktar North Star dokümanı yardımcı olabilir
  • Yazıyla ifade etmek ilk kod taslağından daha verimliyse ya da henüz kod tabanına onboarding yeterli değilken geri bildirim için bir taslak bırakmak isteniyorsa kullanışlıdır
  • Şirket, ilk çözümü atacak disipline sahip olmadan doğrudan production dağıtımını zorlarsa prototip olduğu gibi “çözüm”e dönüşebilir
  • Junior çalışanların senior geliştiricinin fikir uygulamasına itiraz etmekte zorlandığı organizasyonlarda, daha güvenli şekilde soru sorulabilen daha yumuşak bir çıktı gerekebilir

• Tasarım dokümanlarının kötü nedenlerle kullanıldığı durumlar

  • Disiplini veya yetkinliği eksik ekiplerde süreci yavaşlatmanın bir aracına dönüşebilir
  • Dokümantasyon amacıyla kullanılsa bile genellikle hızla eskiyip güncelliğini yitirir
  • Her tasarım sorusuna en baştan cevap vermek zordur; gerçek problemler çoğu zaman ancak kod yazıldıktan sonra ortaya çıkar
  • Ekip yeterli disiplini kurabiliyorsa, “tasarım”dan çok hackleyerek öğrenme yaklaşımı daha verimli olabilir

[GN⁺]

Hacker News görüşleri

• Buna prototipleme denir; tasarım sürecinin değerli bir parçasıdır ve bazıları buna “pathfinding” de der.
  Bunların hepsi tasarıma girdi sağlar, ama uygun ölçekte bir tasarım hâlâ gereklidir. Aksi hâlde o an ne çalışıyorsa onu yapmaktan ibaret olur. Çözmeye çalıştığınız sorunun ne olduğunu ve çözümün ne olduğunu tanımlamanız gerekir. Bazen resmî inceleme gerektirmeyen 1 sayfalık bir belge yeterlidir; bazen de haftalar süren inceleme ve geri bildirim döngülerinden geçen çok sayfalı bir belge gerekir.
  Unutmayın: “Haftalarca kod yazarak birkaç saatlik planlamadan tasarruf edebilirsiniz” ;)

  • Tasarım mutlaka anlaşılmalıdır, ama bu illa bir belge ya da kalıcı çıktı anlamına gelmez. Kalıcı bir kayıt gerekiyorsa PR da gayet iyi bir mecra olabilir.
    Hatta tersinin çok daha sık doğru olduğunu gördüm. İnsanlar planlar, tekrar planlar; sonunda plan, anlamsız olmanın ötesine geçip üretkenliğe aktif olarak zarar vermeye başlar.
  • Bu daha çok bir “ya o ya bu” meselesine yakın. Tasarım ve prototip ikisi de gerekir.
    Haftalarca kod yazmak birkaç saatlik planlamayı kurtarabilir, ama haftalarca plan yapmak da boşa gidebilir. Kâğıda mantıksız ya da imkânsız şeyleri yazmak kolaydır. Örneğin “bir unicorn filosunu yarı üzgün bir renge boyamak” gibi.
    İdeal olan, tasarım ile prototipin birlikte evrilmesi; bir taraftaki yinelemenin diğer taraftaki bir sonraki yinelemeyi ileri iterek DNA’nın çift sarmalı gibi sarmal biçimde gelişmesidir. Prototip yapmaya doğru eğilmenin büyük avantajı, bir tur bittiğinde geriye gerçekten bir şey yapan yazılım kalmasıdır. Bir tasarım turu bittiğinde ise pratikte geriye pek bir şey kalmaz.
  • İkisini birden yapmamak için bir neden yok. Bence önce teoriyi yazmak, sonra prototip ile bunun olup olmayacağını göstermek, ardından asıl tasarım belgesini yazmak daha iyi.
    Ve uygulama aşamasına kadar kodun atılabilirliğine öncelik vermeyi sürdürmek gerekir. Silmesi ne kadar kolaysa o kadar iyi.
  • Kesinlikle doğru: prototipleme ve pathfinding tamamen uygundur ve çoğu zaman gereklidir.
    Ama tasarım belgesi ya da herhangi türden bir spesifikasyon olmadan yapılan yazılım mühendisliği, ne kadar kısa ve öz olursa olsun, mühendislikten çok ağaç ev yapmaya benzer.
    Projenin ölçeği ve önemi büyüdükçe sorunlar ve teknik borç daha hızlı görünür hâle gelmeye başlar.
  • “Haftalarca plan yaparak birkaç saatlik kod yazmaktan da tasarruf edebilirsiniz” :)

• Yazmak, problem alanını keşfetmek için gerçekten yararlıdır.
  Problemi kesinlikle anladığımı sandığım, ama yazmaya başlayınca yeni ve önemli soruların ortaya çıktığı çok oldu. Bunlar genellikle soyutlanmış bir bakış açısından daha iyi görünür ya da ilk birkaç yayın kilometre taşında ortaya çıkmayabilir.
  Kariyerimin başlarında tanıştığım bir mentoru hatırlıyorum. Bir ödeme ağ geçidi için sonradan active/active yapı tasarlamıştı; Lucidchart’ı açıp “bu diyagram hayatımın 6 ayını temsil ediyor” demişti.
  Her zaman gerekli ya da faydalı değildir, ama gerektiğinde birkaç günlük planlama haftalarca kod yazmayı kurtarabilir.

  • Matematik diploması olan bir yöneticim vardı; TV ya da filmlerdeki matematikçiler gibi baştan sona akışı beyaz tahtaya çizerdi.
    Sorun çıkacak noktaları çok önceden öngörebildiği için projeler hep sorunsuz ilerlerdi. Bir sorun ya da belirsizlik gördüğünde sadece o kısmı modeller, sonra tekrar beyaz tahtaya dönüp devam ederdi.
    Benzetmek gerekirse bu, haritayla bir araba yolculuğu planlamaya benzer. Günümüzde tasarım belgeleri sadece yolu işaretleyip hemen sürüşe geçmek gibi; o yöneticinin beyaz tahta haritası ise yakıtın nereden alınacağını, turistik yerlerin çalışma saatlerini, sınır geçiş belgelerini, toplam bütçeyi, acil durum kitini, Plan A ve Plan B’yi bile “aşırı planlıyordu”.
    Aşırı sıkıcıydı ama atılacak koddan çok daha iyiydi. Artık aşırı planlamamak bana tembellik gibi geliyor.
    Elbette “herkesin yüzüne bir yumruk yiyene kadar bir planı vardır” sözü doğru, ama bu savaş, siyaset ve müzakere için geçerlidir; kod yazmaya pek uymaz.
  • Yazmanın yararlı olduğuna katılıyorum. Ama kod yazmanın da aynı etkiyi yarattığını düşünüyorum. Deneyimime göre keşif için ikisinin birlikte gitmesi gerekir.
    Sonuçta iyi bir PR da bolca yazı içerir ve aynı etkiyi yaratır. İyi belgelenmiş bir taslak PR’ın, salt bir tasarım önerisinden daha iyi olduğunu düşünüyorum. Çünkü yalnızca yazı yazınca, ancak kodun içindeyken akla gelen önemli kısıtları unutursunuz.
  • “Yazmak, doğanın size düşüncelerinizin ne kadar gevşek olduğunu gösterme yoludur.”
    -- Dick Guindon

• Tasarım belgelerinde yaşadığım en büyük sorun, kimsenin onları okumaması. İşveren istese bile durum aynı.
  Prototiplemede yaşadığım en büyük sorun ise insanların bunu “yayın kodu” olarak görüp nihai kod olarak kullanmaya zorlaması.
  Bu yüzden karma yaklaşım en iyi sonucu verdi. Planlama ve dokümantasyona çok zaman ayırıyorum ama temelde bunu kendim için yapıyorum; daha sonra nihai üründe kullanılması sorun olmayacak şekilde yayın kalitesinde prototip kodu yazıyorum.

  • İnsanların ortalama bir tasarım belgesini okumak istememesinin nedeni, ortalama bir yazılım mühendisinin kavramları açık ve öz biçimde ifade edecek yazma becerisine sahip olmamasıdır.
    Tasarım belgeleri, yazarı dışında kimsenin doğru dürüst anlamadığı ham not yığınlarına dönüşür; insanlar da bu tür notları okumaktan çekinir.
    Ama tasarım belgesi yazarına bunun okulda not verilen bir dönem sonu raporu gibi olduğunu söylerseniz, birkaç kez yeniden yazarak metin epey iyileşebilir. Belirti prototiplemeyle aynıdır. İnsanlar taslak kalitesinde bir tasarım belgesi yazıp, bunun sihirli biçimde daha geniş bir okur kitlesine uygun iyi bir yazıya dönüşmesini bekler. Prototip kodun birkaç kez refactor edilmesi gerektiği gibi, tasarım belgelerinin de birkaç tur düzenlemeden geçmesi gerekir.

• Sözleşmenin yenilenmesini önlemek için son tarihe kadar bir şeyler yapıp yayımlamamız gerekiyordu; o sözleşme de milyonlarca dolara mal olacaktı. Ancak planlanan kaynaklar ve yaklaşımla zamanında bitiremeyeceğimizi fark ettik.
  Bu yüzden geçici, kısmi ve optimal olmayan bir sürümü hızlıca yapabileceğime dair onay aldım; bu sayede zamanında havalanabildik.
  Böylece başkaları kanadın o kısmı için kalıcı ve düzgün sürümü tamamlarken bir süre uçabildik.
  Hatta uçuş sırasında özgün tasarımda eksik kalan gereksinimleri de keşfettik. Bu, düzgün sürümün prodüksiyon yayımını geciktirdi ama ben bunları hack sürümüme hızla ekleyip uçuşu sürdürebildim.
  Hack sürümüm aynı zamanda prodüksiyon destek aracı işlevi de gördü. Kalıcı sürümde hata olup durdurulması gerektiğinde alternatif yol da oldu. Kısmi ve eksik bir hack, ama avantajları var.
  Kullandığım dilin daha az yaygın olması nedeniyle şikâyet edenler de oldu. Ama mevcut kaynaklar ve yaklaşımla baştan havalanamayacağımızı unutmamak gerek.
  Son tarihe yetişmek için tercih edilen dilde daha fazla ya da daha hızlı geliştiricilere ihtiyaç olurdu. Mevcut çalışanlardan biri, ben dâhil, tercih edilen dilde benim niş dildeki hack’im kadar üretken olacak zamana ve beceriye sahip olsaydı, o kişi kalıcı çözümü zamanında yapmakla görevlendirilirdi. Böyle bir seçenek yoktu.
  Her hâlükârda mevcut bir prodüksiyon destek aracı varsa, prototip özelliklerin bir süre kalabileceği bir yer de vardır.

  • Hangi dildi?

• Bu da başka bir görüş yazısı; veri yok, somut örnek bile yok.
  Her yazılım mühendisinin güçlü fikirleri olduğunu biliyorum ama bu zayıf bir argüman. Neyin doğru olduğunu görmek için çok kod yazmanın işiniz olduğunu düşünüyorsanız yakında yerinizi GPT alacak. Çünkü bunu daha hızlı ve daha ucuza yapabilir. Zor kısım her zaman neyin yapılması gerektiği konusunda uzlaşı sağlamakta; kod yazarak bu sorundan kaçamazsınız.

  • Kesinlikle katılıyorum. “Tasarım dokümanı” doğru ifade mi bilmiyorum; ben buna teknik analiz diyorum. Ama iş ve ürün gereksinimlerini uygulama ayrıntılarına bağlayan dokümanlar yazmak, gereksinimler ve teslimatlar konusunda herkesin aynı anlayışa sahip olmasını sağlamak için çok faydalı.
    Gereksinimler netse ve ne teslim edeceğim herkes için açıksa buna gerek yok. Doğrudan prototiplemeye geçilebilir. Ama ciddi projelerde bu durum nadirdir. Paydaşlardan ortaya çıkarılması gereken, bilinmeyen bilinmeyenler her zaman vardır; teknik analiz de bunu yapmanın iyi bir yoludur.
  • Benim demek istediğim de tam olarak bu. “Anlatma, göster” yaklaşımının daha iyi bir uzlaşı yarattığını düşünüyorum.
    Dikdörtgenler ve kesik çizgilerin sınırı var. Gerçek koddan uzak kaldığınızda gerçek kısıtları unutuyorsunuz. Sizi gerçekten yavaşlatan şeyler Google Docs’ta görünmüyor. Deneyimlerime göre “Benim düşündüğüm şey bu” deyip taslak PR göstermek daha ileri götürüyor.
    Ve evet, bu %100 bir görüş. Kişisel blog; hakemli makale değil :) Yanılmak sorun değil.
  • Atılacak kod, somut bir örnek olduğu için tasarım dokümanından daha iyidir.
    Kod gibi konuşmayı sabitleyecek somut bir şey yoksa, soyut tasarım üzerine tartışmalar eninde sonunda “benim hayalimdeki ip senin hayalindeki ipten daha uzun” türünden sonuçsuz çekişmelere dönüşür.
  • Bu inanca sahip birinin LLM ile çok daha hızlı hareket etmesi, LLM’in bu işi tamamen ikame etmesinden daha olası.
  • Bu tür yazılardaki “veri” bazen onlarca yıllık kişisel deneyim olabilir.

• Deneyimlerime göre koda verilen geri bildirim ile tasarıma verilen geri bildirim inanılmaz derecede farklı türlerde oluyor.
  Tasarım dokümanları herkesin problem alanını düşünmesini sağlayan “neden” sorularını teşvik eder. Örneğin “Şirkette henüz Rust’ta yetkin kimse yokken neden Rust web sunucusu öneriyorsunuz?” gibi yorumlar yapılabilir.
  Bu tür incelikli soruları prototip çalışmaya başladıktan sonra sormak çok daha zor olur. Kolayca “Ekibin deneyimi neden önemli ki? Bakın gayet iyi çalışıyor! Engel olmazsanız prototipi biraz cilalayıp bir hafta içinde prodüksiyona alabiliriz!” noktasına gelir.

  • Bu illa kötü bir şey değil. Pek çok “neden” sorusu gerçekten verimsiz bisiklet kulübesi tartışmasıdır.
    Özellikle çalışan kod yerine sadece tasarım incelenirken daha da böyledir.

• Yazılım işinin temiz ve düzenli bir akıştan geçtiğini hayal ederiz.
  Tasarım dokümanı yazılır, PR’da özelliği yayımlamak için küçük ve artımlı değişiklikler yapılır, Git geçmişi temiz ve düzenlidir. Sürekli ileri gidiş gibi görünür.
  Bunu kim böyle hayal ediyor? Yazılım mühendisliği dersi veren profesörler mi?
  Bu bana düzyazı, deneme, hikâye, roman vb. şeylerin önce ana hatları çıkarılıp sonra bunun düzyazıyla “doldurularak” yazıldığını düşünen insanları hatırlatıyor. Sanki bu süreçte belgeyi yeniden yazmayı ya da yeniden yapılandırmayı gerektiren hiçbir keşif olmayacakmış gibi. Kimse böyle yazmaz. İlk taslaklar her zaman berbattır; iyi yazıların neredeyse tamamı büyük ölçüde düzeltilmiş hâlleridir.
  Kod yazmak, ev ya da köprü inşa etmekten çok yazmaya daha yakındır.

  • Yeni yazılmış kodu debug etmekte her zaman büyük değer görüyorum.
    Yeni mantığı satır satır takip etmek, değişkenlere ve belleğe bakmak kodu iyileştirmeye gerçekten yardımcı oluyor. “Aa, bu yerel değişkene gerek yokmuş”, “buraya debug etmeyi kolaylaştırmak için geçici bir değişken eklemeliyim”, “üzerinde döndüğüm koleksiyon boşsa bu kod tuhaf davranıyor” gibi şeyler keşfediyorum.
    Kaç yaşında olursam olayım, ne kadar çok kod yazmış olursam olayım, yeni yazdığım kodu debug ederken hep yeni bir şey keşfediyorum. Bu, bir yazarın taslak yazdıktan sonra onu yeniden okumasına ya da kendisine veya başkasına sesli okumasına benzetilebilir.

• Tasarım kararlarını tek bir dokümanda resmileştirmeye çalışmak yerine, bunları süren bir yorum dizisi olarak kaydetme sürecini gerçekten seviyorum.
  Ben GitHub issue’larını böyle kullanıyorum ama işlevsel olarak PR kullanmakla aynı şey. PR aslında kod branch’i eklenmiş bir GitHub issue’sudur.
  Benim yöntemim hakkında daha fazla yazdığım yazı burada: https://simonwillison.net/2022/Jan/12/how-i-build-a-feature/...

  • O zaman her issue için güncel uzlaşıyı nasıl aktarıyorsunuz? Örneğin aylarca süren iletişimi taramak istemeyen yeni katılan birine ya da dizide sürekli yer almış ama belirli bir konuda ekibin nerede uzlaştığını kolayca bulamayan bir ekip üyesine bunu nasıl iletiyorsunuz?
    Başka bir deyişle, o diziyi nihai dokümana nasıl özetliyorsunuz?

• İkisinin birbirini dışladığını düşünmüyorum
  Tasarım dokümanı daha geniş bir kavram; amaç iletişimdir
  Bazen kod dışı yollarla aktarmak gerekir. Diyagramlar, görseller, yazılar vb. gerekir

  • Katılıyorum
    Yazarı olmayan ya da koda çok aşina olmayan birinin değişiklikleri tek bakışta anlaması çok zordur. Okuyanın değişikliği bağlam içinde anlamak için doğru zihinsel modeli hızla oluşturabilmesi adına üst düzey açıklamalara ve dokümantasyona ihtiyaç vardır
    1000 satırlık bir diff'e bakıp onun ne yaptığını ve daha da önemlisi üst ve alt akışta ne gibi etkileri olacağını doğru şekilde söyleyebiliyorsanız, ya yalan söylüyorsunuzdur ya da gerçekten kıskanacağım kadar kusursuz biçimde kapalı ve doğrulanabilir bir ortamda çalışıyorsunuzdur

• Tasarım dokümanları, olası seçenekler arasından prototip sayısını 2–3'e indirmeye yardımcı olur. Tamamen yeni bir şey eklemek için keşif yaparken özellikle faydalıdır
  Göstermenin anlatmaktan daha iyi olduğunu hissediyorum; ancak yeni katılan biri kod yerine tasarım dokümanı üzerinden daha kolay anlar