Chesterton’ın orta parmağı

• Chesterton’s fence, nedenini bilmediğiniz kodu gelişigüzel değiştirmemenizi öğütler; ancak nedenini bırakmadan yazılmış kod ve commit geçmişi aynı yükü sonraki geliştiriciye devreder
• Bu deponun son 13 yıldaki commit gövdeleri komut satırı ölçümüne göre yalnızca 295 satır; dependabot, revert ve typo ile ilgili gövdeler çıkarıldığında sayı 167 satıra düşüyor
• Commit başlıkları büyük değişikliklerde bile “fix page A” gibi bağlam sunmuyor; ayrı dokümantasyon ve kod yorumları da neredeyse olmadığından değişikliklerin nedenini izlemek zorlaşıyor
• Kodda yarım kalmış refaktörler, kaldırılmış özelliklerin kalıntıları, eklenmiş ama bağlanmamış ya da kullanılmayan özellikler ve görünüşe göre kimsenin kullanmadığı özellikler duruyor
• Commit mesajları ve dokümantasyon en azından “neyin değiştiğini, neden değiştiğini, bunun neden iyi bir çözüm olduğunu” bırakmalı; hiçbir şey bırakmamak, sonradan gelen geliştiricilerin maliyetini büyütür

---

Nedensiz kodun bıraktığı yük

• Chesterton’s fence, bir şeyin neden öyle yapıldığını anlamadıysanız onu gelişigüzel değiştirmemeniz gerektiğini anlatan bir benzetmedir
  • Programlamada da tuhaf görünen bir kodu “düzeltip” daha sonra o tuhaflığın aslında bir nedeni olduğunu fark ettiğiniz durumlar olabilir
• Bu vakada ise bunun karşı tarafındaki sorun ortaya çıkıyor
  • Tuhaf kod ve karar çok, ama neden öyle olduğuna dair hiçbir kayıt yok
  • Önceki geliştiricilerin hepsi ayrılmış; soracak kimse de kalmamış
• Deponun commit geçmişi pratikte neredeyse hiç bağlam sağlamıyor
  • Son 13 yıldaki commit gövdeleri toplam 295 satır
  • dependabot, “revert commit” ve “fix typo” commit gövdeleri elle çıkarılınca 167 satır kalıyor
  • Bu da kabaca ayda bir satır seviyesine denk geliyor
• Commit başlıkları da çoğunlukla “fix page A” gibi, büyük değişiklikleri açıklamak için yetersiz
• Ayrı bir dokümantasyon yok ve kod yorumları da neredeyse hiç yok
• Bu durum, “çok sayıda tuhaf şey yaptık ama neden yaptığımızı söylemeyeceğiz” diyen bir Chesterton’ın orta parmağına daha çok benziyor

Geliştiricinin bırakması gereken asgari kayıt

• Kod tabanında çeşitli türlerde yarım kalmış ya da artakalmış kodlar bulunuyor
  • Bitmemiş refaktörler
  • Kaldırılmış özelliklerin kalıntıları
  • Eklenmiş ama bağlanmamış ya da kullanılmayan özellikler
  • Görünüşe göre kimsenin kullanmadığı özellikler
• Genel olarak Chesterton’s gap sorunu da ciddi görünüyor
  • “Henüz çit yok, o halde bir tane yapalım” yaklaşımı; gerçekten bir çite ihtiyaç olup olmadığını sormayan bir duruma benziyor
• İyi yazmak zordur, ama kabaca yeterli bir açıklama bırakmak zor değildir
• Değişiklik kaydı temelde üç soruya yanıt vermelidir
  • Ne değişiyor
  • Neden değişiyor
  • Bu çözüm neden iyi
• Bazen yalnızca “Implement new feature X” yeterli olabilir; ama çoğu durumda, özelliğin neden veya nasıl bu şekilde eklendiğine dair yazılacak şeyler vardır
• Hata düzeltmeleri, refaktörler ve anlamlı değişikliklerde genelde en az bir-iki paragrafla neyin değiştiği ve neden değiştiği bırakılabilir
• Bu tür kayıtlar isteğe bağlı değil, yazılım geliştiricisinin işinin bir parçasıdır
  • Süslü olmasına gerek yok
  • Kusursuz İngilizce olmasına gerek yok
  • Gösterişli bir deneme olmasına gerek yok
  • Eksik kalan şeyler olsa bile, bu yine de hiçbir şey olmamasından çok daha iyidir
• Hiçbir şey bırakmamak, sorunu sonradan gelen herkesin üzerine yıkmak demektir

[GN⁺]

Lobste.rs görüşleri

• Sonradan neyin önemli hale geleceği o anda her zaman net olmayabilir. Commite kadar uzanan tüm sürecin açık biçimde kayda geçirilmiş olması büyük fayda sağlar, ancak ilgili herkes zaten çok fazla bağlama sahip olduğundan “fazlasıyla bariz” sayılıp atlanan şeyler de olur
  Tartışma kayda geçirilmezse, karar alma sürecini dijital arkeoloji gibi kazıp çıkarmak çok daha zorlaşır. Sonunda neden o çitin orada olduğunu bilmediğiniz bir durumla uğraşmanız gerekebilir; böyle zamanlarda bunu mevcut bağlam ve bugünkü insanların sistem bilgisi temelinde değerlendirmek gerekir
  Projede uzun süre kalıp tüm sisteme dair anlayış ve sezgi edinmiş birinin varlığı büyük yardımcı olur. Geliştiricileri birbiriyle değiştirilebilir dişliler gibi gören organizasyonlarda kimse yeterince uzun kalmaz; böylece aynı hatalar tekrarlanır ve tekerlek yeniden icat edilir

  • Code review’dan elde edilen en büyük fayda, başka birinin kodu okuyup gerekçenin açık olmadığı her yere yorum yazmasını sağlamasıdır. Bana açık olmayan yerlere zaten yorum eklediğim için, artık iki kişiden en az birinin açıklamaya ihtiyaç duyduğunu hissettiği yerlerde yorum kalmış olur
    Sonraki kişinin koda baktığında bunun neden böyle olduğunu anlama ihtimali artık sıfır olmaz
  • Bu, eski yemek tariflerinde “herkesin nereden bulacağını bildiği” malzemelerin yazılmamasına ya da ortaçağ müziğinde ritim ve ölçünün “zaten herkesçe bilindiği” varsayılmasına benziyor. Bugün artık içinde ne olduğunu bilmiyoruz

• Commit mesajına sadece “fix” ya da “WIP commit” gibi şeyler yazan geliştiricileri hiç anlayamadım. Muhtemelen hiç ciddi bir kod arkeolojisi yapmamışlardır ya da böyle bir şeyin yapılabileceğini akıllarına bile getirmemişlerdir
  Ben hep fazla bilgi verme yönünde hata yapmaya çalışıyorum. Böylece gelecekteki ben, benden sonra gelecek kişi ya da bir arıza çıktığında nöbete çağrılan talihsiz kişi, bir şey bozulduğunda en azından nedenini bulma şansına sahip olur

  • Bu muhtemelen iş biriminin boyutunun yanlış ayarlanmış olması olabilir. Bazı geliştiriciler için tek bir commit, “satılabilir” tek bir özellik üretmek üzere gereken yüzlerce küçük adımdan biri olabilir
    Böyle durumlarda her kontrol noktasından sonra neyin değiştiğini zihinde takip etmek ya da anlamlı bir açıklama eklemek zordur; commit’i iyi tanımlanmış iş birimlerine ayırmanın bir aracı olarak değil, video oyununun “save” düğmesi gibi kullanmaya daha yakındır
    Tersine, büyük bir API refactor sonucu büyük bir commit oluşturuyorsanız, tasarım belgesine yakın bir açıklama bile yetersiz kalabilir; bunu yapmayacaksanız uzun bir mesajın anlamı da belirsizleşir. Ama bazı insanlar bunu bir rozet gibi görüp release notlarına “hata düzeltmeleri ve işlev iyileştirmeleri” gibi ifadeler yazmaya başlıyor; bu ise açıkça yanlış bir sonuç

• Bir değişikliğin arka planını okuyup anlaması gereken “başka kişi”nin gelecekteki kendileri olabileceğini birçok geliştirici sık sık unutuyor. Bir kod bloğuna bakıp kafanızı kaşıdıktan sonra git blame çalıştırıp karşınızda kendi adınızı bulma durumu herkese tanıdık geliyordur
  İyi commit mesajları, neden sorusunun peşine düşmek için issue’ları, e-postaları ve sohbet kayıtlarını didikleyerek harcanacak saatleri, bazen günleri, sayısız kez kısalttı. Hatta normalde cevabı hemen bilmem gereken durumlarda bile
  Gelecekteki kendinize karşı nazik olun. Bildiğiniz, düşündüğünüz ve tartışılmış olan her şeyi git log’a dökmek daha iyidir. 5 yıl sonra neyin hâlâ apaçık olacağı asla belli değildir

  • Elbette bu tür bilgilerin bir kısmı commit log’unda değil, yorumlarda ya da tasarım belgelerinde yer almalı olabilir
  • git blame içinde kendi adımı görüp afalladığım durumlar, en azından arkasında gerçekten bir neden olan şeylerde çok sık yaşanmıyor. Başkasının garip davranışı gibi rastgele durumlarda, onların sürecini göremiyorsanız faydalı bir açıklama sunmak zordur; ama bir zamanlar bana mantıklı gelen bir şeyse, tekrar okuyunca genelde yeniden anlam kazanır
    Sanırım benim öğrenme biçimim lav katmanları gibi birikerek oluşan bir yapıya daha yakın. Liseden beri kökten değişmektense, bildiklerimin ve onları kullanma yollarımın üzerine sürekli yenilerini ekledim

• Kısa süre önce biri commit mesajı bir cümleyi aşıyorsa bunun genelde zaman kaybı olduğunu savundu; buna güçlü biçimde karşı çıkmak istedim ama tersini kanıtlamakta düşündüğümden daha beceriksiz kaldım
  Sorulardan biri, hangi bilginin commit mesajına girmesi gerektiği ve hangi bilginin satır içi yorumlara, ADR'lere ya da diğer uzun biçimli belgelere gitmesi gerektiği
  Hâlâ iyi commit mesajları yazmaya çalışıyorum ama iş yerinde artık umudu kestim, kişisel oyuncak projelerimde de tutarlı olamıyorum

  • Benim için commit mesajları reviewer içindir. Bu değişikliğin neden gerekli olduğunu, neyi düzelttiğini ya da neden yeni bir özellik istendiğini anlatır ve değişikliği anlamak için bir çerçeve sağlar
    Ama nihai kod, commit mesajı okunmadan da anlaşılabilir olmalıdır. Yeni kodun içinde gerekçe gerektiren bir şey varsa bu yoruma girmelidir
    Başka bir deyişle commit mesajı bu değişikliği neden şimdi yaptığımızı açıklar, yorumlar ise değişiklik tamamlandıktan sonraki kodun neden o durumda olduğunu açıklar
    Daha büyük değişiklikler, özellikle de yeni özellikler için, bir yerde mutlaka bir tasarım belgesi olmalıdır. İnceleme gerektiriyorsa depodaki gerçek bir belge olabilir ya da issue takip sisteminde bulunabilir
    Commit mesajı bu belgeye işaret etmeli ve tasarımın koda inerken ortaya çıkan ayrıntıları da açıklaması gerekebilir. Mümkünse tasarım belgesinin kısa bir özetini de eklemek iyidir. Birden fazla potansiyel reviewer olduğunda, en çok kimin ilgilenmesi gerektiğine dair sinyal verir ve özellikle tasarım aşamasında geri bildirim vermesi gerekirken dışarıda kalmış kişileri yakalamak açısından önemlidir
  • Commit mesajına ne koyacağıma karar verirken kullandığım ölçüt şu: genelde commit mesajlarını git log ya da jj log ile değil, neredeyse her zaman satır açıklaması görünümü üzerinden görüyorum
    Başlık satırı, daha derine inmeye gerek olup olmadığına karar vermek için genel olarak çok faydalı. Gövdede değişikliğin neden yapıldığına dair bilgi olması, gerekçenin sezgisel olmadığı durumlarda yardımcı oluyor
    Örneğin epey kod eklenmiş olsa bile çoğu zaman sadece “admin: add impersonation” yeterli olabiliyor. Ama “auth: shorten JWT timeouts” ise, neden zaman aşımı sürelerinin kısaltılması gerektiğine dair bir iki cümle görmek isterim
    Gerçekten uzun biçimli commit mesajlarının pratikte pek de yararlı olmadığını düşünüyorum. Yazıda işaret edilen nedenlerle de büyük ölçüde aynı. Bu tarz, commit mesajının fiilen PR açıklaması olduğu iş akışlarından, örneğin e-posta tabanlı akışlardan ya da Gerrit'ten çıkmış gibi görünüyor. Böyle durumlarda zararlı değil ama mutlaka değer kattığını söylemek de zor
  • Geçmişte tam da bu soruya cevap vermek için bir yazı yazmıştım. Farklı belge konumlarını bir hiyerarşi içinde ele alıp bilgiyi nereye koymak gerektiğine dair pratik kuralları derlemiştim
    Ben de benzer durumdayım. İş yerindeki daha geniş grupta ayrıntılı commit mesajları yazan sadece ben ve bir başka kişi var

• Çitin neden yapıldığını bilseniz bile, neden şu anda orada durduğunu bilmiyor olabilirsiniz. Hatta Chesterton’ın çitini yapan kişi olsanız bile onu yıkıp yıkamayacağınızı bilemeyebilirsiniz
  Sistem kurulduğunda amaçlanan bağımlılık ağacı, herhangi bir andaki gerçek bağımlılık ağacının yalnızca bir alt kümesidir. Bu yüzden kusursuz bir geliştirici size çitin neden yapıldığını tamamen anlatsa bile bunun faydası sınırlıdır
  Onların bildiği şey neden yapıldığıdır; “bu çiti kaldırırsam ne bozulur?” sorusunun cevabı değildir. https://xkcd.com/1172/ buna bakmak yeterli. Komik kullanım örneklerinden önemsiz sayılabilecekler olabilir, ama asıl geliştiricinin kendisinin bile bilemeyeceği meşru kullanımlar her zaman vardır
  Asıl geliştiricinin ne düşündüğünü ya da ne içtiğini bilmek güzeldir, ama bu bilgi eksiklik ile alakasızlık arasında bir yerde durur
  Uydurma bir örnek olarak, Chesterton’ın çitinin başlangıçta iki yanında çiftlikler varken çocukları su birikintisinden uzak tutmak için dikildiğini varsayalım. Şimdi bir otoyol yapılmış olabilir ve o çit tesadüfen geyiklerle arabaların çarpışmasından kaynaklanan kitlesel hayvan ve insan ölümlerini önleyen tek şey haline gelmiş olabilir
  Bunu kimse bilmiyor. Otoyol + çitsiz kombinasyonu yalnızca test edilmemiş değil, hiç var olmamıştır da; otoyolu yapanlar ile doğal kaynaklar dairesi o yolda neden az hayvan çarpması olduğunu bilmiyordur. Birkaç yıl sonra bütün çiftlikler konuta dönüşüp orası artık büyük bir hayvan geçiş koridoru olmaktan çıkınca çit işe yaramaz hale gelebilir de, gelmeyebilir de
  Bu size zorlama ya da kendinizle ilgisiz geliyorsa sizi kıskanırım. Benim deneyimime göre belli bir ölçeği olan ve çok yeni olmayan şirketler dışında işler genelde böyle yürür
  Gerçek şu ki yaptığımız her şey bir ekosistemin parçasıdır; açıkça etkileşime girmeyi hiç kararlaştırmadığımız şeylere dayanır ve onlar tarafından da kullanılır. API yüzeyini küçültebilir ve tüm uygulama ayrıntılarının komşunun işi haline gelmesini engelleyebilirsiniz, ama istenmeyen bağlanma artan entropi kadar kaçınılmaz bir evren yasasına yakındır
  Bazı insanlara bu nihilist ve yenilgiyi kabullenmiş gibi gelir. Entropiyle savaşmamız gerekmez mi diye sorabilirler. Ama bana göre zamanı en iyi kullanma ve yatırımın karşılığı, bunun temelde savaşılacak değil yönetilecek bir şey olduğunu kabul etmekten gelir
  Dünyanın durumunu her zaman bilebileceğinizi varsaymak, başarısızlığı ve kendini suçlamayı peşinen kabul etmektir. Tıpkı %100 uptime diye bir şey olmaması ve çoğu hedef için bunun yanlış bir hedef olması gibi
  Sürecin belli bir Heisenberg tarzı belirsizlik taşıdığını kabul ederseniz, bir günde elinizdeki sınırlı zamanı daha iyi sonuç üretmek için nasıl kullanacağınızı seçebilirsiniz. Özellikle de proaktif ve reaktif yaklaşım arasında akıllıca bir denge kurabilirsiniz; reaktif çalışmayı sıfıra indirmenin mümkün olmadığını ve bazen bir günlük reaktif işi önlemek için bir yıllık proaktif iş yapmanın anlamsız olduğunu da anlarsınız
  Peki commit’e ne kadar dokümantasyon yazılmalı? Kaç tane tasarım dokümanı ya da test planı olmalı? Ben de bilmiyorum. Ama bir seçenek ortaya atayım: bütün dokümantasyon bir okur için yazılır
  Kod tabanını değiştiriyorsanız mevcut ekip üyeleri ve sonradan katılanlar dahil herkes araştırma yaparak değişikliğin ne yaptığını ve neden yapıldığını anlayabilmeli; ayrıca tehlikeli basamak taşları ya da yük taşıyan bug’larla ilgili birkaç uyarı da bulunmalı
  Bu, uzun bir düzyazı değil; sahneyi kuran ek bağlama işaret eden göstergeler biçiminde olmalıdır. Örneğin: “Bu adımda kimlik doğrulama istememizin nedeni, tüm değişikliklerde çok taraflı onay gerekmesi politikamızın bir parçası olmasıdır. see: go/multiparty” gibi

  • Entropinin artması ve istenmeyen bağlanmaların durmadan ortaya çıkması aslında bir kusur değil, sistemlerin kalıcı bir duruma saplanıp kalmasını engelleyen yararlı bir özellik olarak bile görülebilir
    İnsanlarla uğraşırken mükemmelliği hedefleyen sistemler gerçekten rahatsız edicidir. DRM, trusted computing, remote attestation, Faro Plague, smart contracts gibi şeyler
    Servis modunda yeniden başlatılıp düzeltilebilen sistemler çok daha iyidir. Çünkü yazılımın gelecekte insanlara gerçekten yardımcı olmak için hangi yönde evrilmesi gerektiğini öngöremeyiz. %100 sert biçimde kilitlemektense düzeltmesi kolay hale getirmek daha iyidir

• Biz neredeyse hiç commit gövdesi yazmıyoruz ama başlıkları oldukça iyi yazıyoruz. Ölçüt buysa, neyi ölçen bir ölçüt olduğundan pek emin değilim
  Büyük kod tabanlarında açık kod ve yeterli test coverage çoğu zaman dokümantasyondan çok daha faydalı olur

  • Katılmıyorum. Bazen hem değişikliğin kendisi hem de değişiklik nedeni inceliklidir. Garip bir kodun neden öyle olduğunu anlamaya çalışırken, o commit’te değişen testlere bakmak ek bir adımdır ve neden değiştiğini de mutlaka söylemez
    Tamamen makul bir değişiklik yapılmış ve testler de buna göre güncellenmiş olabilir, ama sonradan bakınca o değişikliğin neden gerekli olduğu hiç net olmayabilir. Özellikle değişen satırlar üretim ortamında beklenmedik ya da ek davranışlar doğuruyorsa daha da böyledir
    Basit bir geri alma istenmeyebilir ve bu noktada değişikliğin neden yapıldığına dair tam geçmiş gerçekten yardımcı olur
    Fikrin doğru olup beklenmedik sonuçların çıktığı pek çok durum gördüm. Niyeti bilirseniz hem yeni sorunu düzeltip hem de ilk değişiklik nedenini koruyan gerçekten doğru değişikliği çıkarabilirsiniz
    Tek satırlık commit’te ısrar ediyorsanız, en azından bilet numarasını ekleyin ki geçmiş oradan okunabilsin

• Böyle kod tabanlarını kurtarmak için 5 yıl boyunca egzotik bölgeleri dolaşıp epey iyi para kazandım. @arp242, her zaman ücretleri artırın ve https://archive.org/details/working-effectively-with-legacy-code kitabını yastığınızın altında tutup uyuyun

• Neyse ki AI zımbırtı üreticileri devasa commit mesajları yazıyor. Bazen gerçek değişiklikle bir miktar ilgili de oluyorlar; yani en azından o kısım çözülmüş sayılır

  • Gerçekten mi? Neyin değiştiğini özetlemekte fena olmayabilirler, ama neden değiştiğini yazmakta pek iyi olacaklarını sanmıyorum