Kod açıklamalarını lütfen basit tutun

 (akselmo.dev)
2 puan yazan GN⁺ 4 시간 전 | 1 yorum | WhatsApp'ta paylaş
  • Kod incelemesinde uzun açıklamalar ile büyük diff'ler birlikte geldiğinde, inceleyen kişinin temel değişiklik nedenini kavraması zorlaşır; bu yüzden commit mesajları, merge request açıklamaları ve yorumlar kısa olmalıdır
  • Açıklamalar neyin değiştiğinden çok neden değiştiğine odaklanmalıdır; birçok değişiklik zaten kodun kendisinden görülebilir
  • Tüm bağlamı tek seferde aktarmaya çalışan uzun açıklamalar, bazı inceleyicilerin odağını ve inceleme hızını düşürebilir
  • Merge incelemesinde atomik commit'ler özellikle önemlidir; küçük düzeltmeler git amend, birleştirme öncesi temizlik ise rebase veya squash ile yapılabilir
  • LLM araçları kullanılsa bile yorumları, açıklamaları ve commit mesajlarını doğrudan yazmak; kodu anlamaya ve inceleme erişilebilirliğine daha çok yardımcı olur

İnceleme açıklamaları “ne”den çok “neden”e odaklanmalı

  • Kod incelemesinde açıklamalar, commit'ler ve merge request'ler aşırı bilgiyle dolduğunda inceleme yükü artar
  • Değişiklikleri uzun uzun sıralamak yerine, asıl önemli olan neden değiştirildiğini açıkça yazmaktır
  • Kodun kendisi çoğu değişikliği gösterebilir ve eksik bağlam varsa inceleyen kişi soru sorabilir
  • Makale gibi yazılmış uzun açıklamalar, odaklanmakta zorlanan kişiler için incelemeyi daha yavaş hâle getirebilir
  • Commit mesajları, merge request açıklamaları ve kod yorumları; net, öz ve yalnızca gerekli bilgiyi içerecek şekilde yazılmalıdır

Commit düzeni ve LLM kullanımına dair talep

  • Commit'ler, özellikle merge incelemesinde atomik olmalı; her değişiklik bağımsız olarak anlaşılabilmelidir
  • Küçük düzeltmeler git amend ile yansıtılabilir, birleştirme öncesinde ise rebase ile düzenlenebilir veya squash yapılabilir
  • LLM araçları kullanılsa bile yorumları, açıklamaları ve commit mesajlarını doğrudan yazmanın daha iyi olduğu düşünülüyor
    • Doğrudan yazma süreci, yapılan değişiklikleri anlamaya yardımcı olur
    • Doğrudan yazılmış açıklamalar, inceleyen kişi için daha erişilebilir olabilir
  • Mümkünse LLM araçlarından kaçınmanın daha iyi olacağına dair kişisel bir görüş de yer alıyor
  • “Erişilebilirlik” ifadesine dair tepkiler olmuş olsa da, asıl nokta kod inceleme açıklamalarını daha kısa ve incelenmesi daha kolay hâle getirme çağrısıdır

İlgili okumalar

1 yorum

 
GN⁺ 4 시간 전
Lobste.rs görüşleri

  • Erişilebilirlik gereksinimlerini belirli bir kişinin tercihleriyle kolayca bir tutmak konusunda dikkatli olmak gerekir
    ADHD sahibi olmak, uzun commit mesajlarından hoşlanmamanın genel bir ADHD özelliği olduğu anlamına gelmez; erişilebilirlik de “ADHD’si olan kişinin sevdiği her şeyi yapmak” değil, genel kullanıcılara aşırı yük bindirmeyen makul düzenlemelere daha yakındır
    Bu yüzden yüksek kontrast, hareketi azaltma, koyu mod gibi erişilebilirlik özelliklerinin çoğu kişinin seçebileceği ayarların arkasında yer alır

    • Daha açık yazabilirdim ama benim AuDHD durumumun düzgün çalışıp işlev gösterebilmesi için belirli koşullara ihtiyacı var
      Uzun metin blokları, örneğin küçük bir değişikliğe A4 boyutunda iki sayfalık açıklama eklenmesi, işi tamamen durdurabiliyor; zorla okumaya çalışırsam bu tükenmişliğe yol açıyor
      Sanırım bunu “bu benim erişilebilirlik gereksinimim ve benzer durumda çok kişi olduğunu biliyorum” diye ifade etmeliyim
      Yine de bunu bir gereksinimden ziyade tercih olarak görenler olabilir, ama commit mesajlarına LLM üretimi metin duvarları eklerken benim gibi insanları da düşünmenizi rica ediyorum
    • Kişiden kişiye değişir ama “önce can alıcı noktayı söyle” talebinin ADHD’nin temel özelliklerinden biri olduğunu düşünüyorum
      Erişilebilirlik açısından bakınca da herkes bu uyarlamadan fayda görüyor; buna karşı çıkmak için özel bir neden göremiyorum
    • Benim deneyimimde nöroçeşitli ve engelli insanların yaşadığı gereksiz zorlukların önemli bir kısmı, erişilebilirlik gereksinimlerinin tercih diye geçiştirilmesinden kaynaklanıyor
      Erişilebilirlik arttığında, o özelliğe eşit bir başlangıç çizgisine gelebilmek için mutlaka ihtiyaç duymayanlar da birlikte fayda sağlıyor; o yüzden bu yönde ilerlemek iyi bir şey

  • AI’dan önce de her zaman aşırı ayrıntılı yorumları tercih ediyordum; birlikte çalıştığım insanların çoğu da buna şaşırıyordu
    Mesela şu metot var: https://github.com/ghostty-org/ghostty/…
    Son 15 yıldır, dilden bağımsız olarak, genel olarak bu tarzda yazıyorum ve AI çağında bunu AGENTS.md içinde de açıkça belirttim
    Bağlantısını verdiğim dosya ve yorumların tamamı insan eliyle yazıldı; AI hiç kullanılmadı
    Nedeni basit: yorum ile kodun birbiriyle uyumlu olmasını gerektiren çift kayıt kuralını dayatıyor
    İkisi uyuşmuyorsa yorum yanlıştır, kod yanlıştır ya da ikisi de yanlıştır; “hangisi doğru değil?” diye sormak bile birçok sorunu yakalamamı sağladı
    Sonuçta kendi projenizde yorumları istediğiniz gibi yazabilirsiniz diye düşünüyorum

    • Bana da bazen koddan çok yorum yazdığıma dair dostane şakalar yapılıyor ama bu tür yorumları gerçekten seviyorum
      Sonradan kodu yeniden okuduğumda o anda aldığım yerel kararların bağlamını koruyor ve gözden geçiren ya da konuya ilk kez bakan kişinin de bağlam kurmasına yardımcı oluyor
      Bu tür yorumlar uzun olabilir ama yazıda sözü edilen “gereksiz ayrıntılar” bunlar değil; paylaşılan örnek de “ne yaptığını değil neden yaptığını açıkla” özdeyişine iyi bir örnek gibi görünüyor
    • Bu tür yorumlar harika
      Örnekteki gibi, macOS kullanıcılarının kabuk ayarlarını ~/.bash_profile içine koyup login shell davranışı beklemeye neden başladığını açıklayan bir yorum, belirli bir kararın neden alındığına dair yararlı bağlam sunuyor
      Ama LLM konusuna dönersek, kişisel olarak henüz o kalitede LLM üretimi yorum görmedim
      Çoğu zaman sadece foo() yapılır, sonra bar() yapılır, en sonunda baz yapılır gibi, kodu okuyunca zaten açık olan şeyleri tekrar etmekten ibaret kalıyor
    • Verilen bağlantıdaki türden yorumlarda sorun yok
      Sorun, küçücük değişikliklere bile devasa tablolar ve madde işaretli listeler eklenen keşmekeşte
    • O düzeyde ayrıntı için gerçekten minnettarım ama kişisel olarak bunun yorumlardan ziyade, o metodu ekleyen commit’in commit mesajında yer almasını tercih ederim
      Commit mesajı kodla her zaman aynı ana ait bir kayıt olarak kalır, ama yorumların zamanla uyumsuz hale gelebileceğini düşünüyorum
      1. satırda başlayan yorum bir başyapıt; yorgunluk hissi doğrudan geçiyor

  • İş yerinde PR şablonuna “bu değişikliğin motivasyonunu ve incelemede dikkat edilmesi gereken önemli tasarım kararlarını doğrudan açıklayın” diye nazikçe yazmayı denedim
    Ama 10 seferin 9’unda o an kullanılan LLM, şablonun tamamını silip yerine eklenen test sayısı, geçen testlere dair onay kutuları ve önemsiz yan dallarla dolu upuzun bir açıklama kusuyor
    Böylece review süreci son derece keyifli hale geliyor

    • İş yerinde bizde de aynı sorun var
      LLM üretimli commit mesajı araçlarını her yere eklemenin iyi bir fikir olduğunu kim düşündü bilmiyorum ama sonuçta commit içinde https://noslopgrenade.com/ sorunu yaşanıyor
      Commit mesajlarında ya da pull request açıklamalarında değişikliğin motivasyonu, tasarım kararları, gerekçe gibi yararlı bağlam yok; bunun yerine sadece koda bakarak anlaşılabilecek uygulama ayrıntılarının paragraflar halinde yazılmış sürümü kalıyor
    • Ben de aynı davranışı gördüm
      agents.md içine “commit mesajı yazarken commit-messages.md dosyasına bakın” maddesini eklemeyi düşünüyorum
      commit-messages.md içine geçen/kalan test onay kutularını yasaklamak, tek tek test sıralamak yerine özetlemek ya da hiç yazmamak gibi commit mesajı yönergeleri koyulabilir gibi duruyor

  • Ne yaptığımı yorum olarak yazdığım zamanlar, bunun neden yapıldığını değil, o yaklaşımın doğru olduğundan emin olmadığım zamanlarla sınırlı
    Tekrarlayan biçimde acı veren tipik neden ise regex

    • Ben de aynıyım
      Her şeyi sağlam şekilde açıklamak gereken zamanlar oluyor ama bugünlerde değişken adı değiştirmek gibi küçük değişikliklere bile devasa açıklamalar eklendiğini görüyorum

  • İlginç biçimde, bana daha çok commit mesajlarımın fazla kısa olduğu söylenmiştir

    • Bu yazıdaki tartışma, ters yöndeki yani açıklamaların fazla kısa olduğundan yakınan Chesterton middle finger yazısıyla yan yana duruyor
    • Fazla kısa olabilir ama oraya bir roman koymak da mantıklı değil
    • LLM’ler gerçekten çok fazla yazıyor
      Bu yüzden claude’un asla yorum yazmaması için ayar yaptım; çünkü ben elle %98’ini siliyor, kalan %2’yi de yeniden yazıyor oluyordum

  • Genelde çok açıklayıcı commit mesajlarını severim ama haber yazısı tarzı bir yapı gibi, en önemli bilgiyi önce verip daha az önemli ama yine de ilgili ayrıntıları sona koymayı tercih ederim
    Örneğin başlıkta en önemli bilgiyi olabildiğince yoğun biçimde toplar, ilk paragrafta değişikliği daha az sıkıştırılmış cümlelerle açıklar, sonraki paragraflarda ise kod değişikliğinin niteliğini gerçekten anlamayı zorlaştırmıyorsa ayrıntılı okunması gerekmeyen ek detayları veririm
    Commit mesajlarının, ileride kodu okuyacak kişi için ne kadar önemli olduğu bence küçümseniyor
    Kod tabanını kurcalarken bir bloğun neden öyle göründüğünü merak ettiğimde, git blame beni ilk bakışta daha iyi görünen ama eksik kalan çeşitli yaklaşımlardan sonra elde kalan seçenek olduğunu çok ayrıntılı anlatan bir commit mesajına götürürse hiç hayal kırıklığına uğramam
    Yazarın ana fikrine dönersek, iletişime açık işaretler eklemek iyi bir ayar ve genel olarak da faydalı
    Commit mesajının ortasına “Bu kodu review ediyorsan burada okumayı bırakabilirsin” gibi bir cümle koyabilirsiniz

  • “Gereksiz ayrıntılar gerekiyorsa sorulur” demek, o kişinin sürekli etrafta olacağını epey cüretkâr biçimde varsaymak demek
    10 yıldan eski bir FLOSS kod tabanına katkı yapmaya başlayınca commit mesajlarını özenle yazmaya başladım
    Kodun neden öyle var olduğunu anlamanın tek yolu git arkeolojisiydi ve Emacs içindeki vc-annonate aracını öğrenip bunu kolayca izlenebilir hale getirdim
    İş yerindeki kodda da bakımını yaptığım kod tabanlarının ilk yazarının çoktan ayrılmış olduğu durumlarla defalarca karşılaştım
    Commit mesajları yalnızca review sırasında okunmaz; hatta birçok review arayüzü commit mesajlarını gizler
    Sorun uzun commit mesajlarının kendisinden çok kötü yazılmış commit mesajları gibi görünüyor
    “Commit mesajlarını, merge request açıklamalarını ve kod yorumlarını açık, amaca dönük, ihtiyaç temelli yazın; neyi değil nedenini açıklayın” ilkesi kulağa iyi geliyor
    Eskiden sadece Fix Bugz 🚀️ yazan birinin şimdi “best practice” izliyorum diye LLM ile commit mesajı yazması da sorun olabilir
    Benim hipotezim, çoğu insanın commit mesajı yazmamasının sebebinin onları okumaması olduğu; okumamalarının sebebinin de GitHub web arayüzü gibi yerlere dayanarak commit'lere bakarken harekete geçme enerjisinin yüksek olması olduğu yönünde

    • “Gereksiz ayrıntılar gerekiyorsa sorulur” sözü review süreci için geçerli
      Bilgi önemliyse yorum olarak bırakılabilir ya da commit mesajına eklenebilir
      KDE birkaç yıldır GitLab kullanıyor

  • Uzun vadede sonraki kuşaklar için başarılı bir git arkeolojisi adına denge gerekiyor
    İnsan değişimi ve bağlamın zihinlerden silinmesi nedeniyle, sonradan o gereksiz görünen ayrıntıları soramayacağınız çok zaman olur
    Bu bağlamı kaydetmenin en iyi zamanı, hâlâ elinizde olduğu andır
    Aslında istenen şey, önemli ayrıntıları önce verip bunları bir özet gibi net biçimde ayırmak olabilir

  • PR ya da kod açıklamaları, ne yaptığınız için değil neden yaptığınız içindir
    Kodun neden bu şekilde göründüğünü ve arkasındaki gerekçeyi anlatmalıdır
    Bu hem review için iyidir hem de daha sonra git geçmişinde kodun neden öyle olduğunu bulmak için faydalıdır

  • Kod açıklamalarını sade tutmak önemlidir
    Çünkü anlaşılamayan ya da odaklanılamayan şey okunamaz
    Aynı zamanda yazılım geliştirirken çok fazla bağlam kaybolur ve şu anda bu bağlam çoğu zaman yalnızca yazanın, onunla konuşmuş kişilerin ya da koda derinlemesine bakmış kişilerin zihnindedir
    Ama bence bu bağlam kodla daha fazla iç içe geçmeli, daha az değil
    Yazarla her zaman konuşamazsınız; bu yüzden bunu her zaman erişilebilir olan ve kodla birlikte güncellenen bir yere yazmak gerekir
    Bugün çoğu geliştirme akışında buna en uygun yer git commit mesajıdır
    En üste bir özet yazmak iyi ama kod değişikliği hakkında ek açıklama da bırakmanızı öneririm
    Şu anda önemli görünmeyen şeyler de dahil bağlamı dışarı çıkarıp kayda geçirirseniz, gelecekteki benliğiniz size minnettar olur
    İleride bu bağlamı yalnızca commit mesajlarına koymaktan daha iyi bir yaklaşıma ihtiyaç var; bu yüzden kişisel olarak kodun “ne”sini ve “neden”ini açıklamak için daha fazla alan tanıyan literate programming yaklaşımını seviyorum