Kodun okunabilirliğini düşüren görsel karmaşıklık kalıpları (2023)

• Yakın zamanda bir kod tabanını incelerken, kodun kalitesine rağmen zihinsel olarak yorucu bir deneyim yaşandı
  • Bunun, kodun karmaşıklığından çok okunabilirlikle ilgili olduğu görüldü
• Kodun okunabilirliğini artırmak için 8 kalıp çıkarıldı

Kod okunabilirliği metrikleri ve alternatif karmaşıklık metrikleri

• Kod okunabilirliğini ölçen evrensel ve yaygın olarak kullanılan bir metrik yok
• Yalnızca pratikte kullanılmayan akademik makaleler ya da kişisel görüşler var
• Yeni bir metrik üretmek yerine, herkesin kolayca tartışabileceği görsel kalıplara odaklanılıyor
• Karmaşıklık metriklerinde önemli koşullar:
  • Kaynak kod parçacıkları veya tekil fonksiyonlar üzerinde çalışabilmeli
  • Algoritmik karmaşıklıktan ziyade kodun yazılış biçimine odaklanmalı
  • Stil unsurlarına (değişken adları, boşluklar, girintileme vb.) odaklanmamalı

Halstead karmaşıklık metriği

• 1970'lerde Maurice Halstead tarafından geliştirilen bir kod karmaşıklık metriği
• Dil ve platformdan bağımsız olarak kodun yazılış biçimini sayısallaştırabiliyor
• Operatör ve operand sayılarına dayanarak programın uzunluğunu, hacmini ve zorluğunu hesaplıyor
• Başlıca ölçümler:
  • Benzersiz operatör sayısı (n1)
  • Benzersiz operand sayısı (n2)
  • Toplam operatör sayısı (N1)
  • Toplam operand sayısı (N2)
• Daha fazla operatör ve operand kullanıldıkça kodun karmaşıklığı artıyor
• Tüm dillerde operatör ve operand tanımları net olmadığından, tutarlı araç kullanımı önemli

Halstead karmaşıklığından çıkan içgörüler

• Kısa ve az değişkenli fonksiyonlar daha okunabilir
• Dile özgü operatörlerin veya sözdizimsel şekerin (syntactic sugar) kullanımı en aza indirilmeli
• Fonksiyonel programlamadaki zincir kullanımı (map/reduce/filter vb.) fazla uzarsa okunabilirlik düşüyor

Bilişsel karmaşıklık (Cognitive Complexity)

• SonarSource tarafından geliştirilen bir karmaşıklık metriği
• Kodu okumanın zorluğunu daha doğru ölçmeye yönelik bir girişim
• Üç temel ilke:
  1. Kısaltılmış sözdizimleri (shorthand constructs) okuma zorluğunu azaltır
  2. Doğrusal olmayan akış kesintileri zorluğu artırır
  3. İç içe kontrol akışı zorluğu artırır

Bilişsel karmaşıklıktan çıkan içgörüler

• Kısaltılmış sözdizimleri özlüdür, ancak potansiyel hata riski taşır
• Koşul ifadeleri ve mantıksal operatörler aşırı kullanılırsa okunabilirlik düşer
• İstisna işleme kod karmaşıklığını artıran başlıca nedenlerden biridir
• goto genellikle kaçınılması gereken bir yapıdır, ancak bazı durumlarda faydalı olabilir
• İç içe kontrol yapıları mümkünse azaltılmalıdır

Fonksiyonun şekli, kalıplar ve değişkenler

• Fonksiyonun görsel "şekli", kod okunabilirliğinde önemli bir rol oynar
• Okunabilirliği artıran üç ilke:
  1. Açık ve belirgin değişken adları kullanın
  • Değişken gölgelemeden (shadowing) kaçının
  • Görsel olarak ayırt edilebilen adlar kullanın (i, j gibi benzer adlardan kaçının)
  2. Değişken yaşam süresini (liveness) kısaltın
  • Değişkenin kullanım kapsamı ne kadar kısa olursa o kadar iyidir
  • Fonksiyon sınırlarını aşarak uzun süre yaşayan değişkenler karmaşıklığı artırır
  3. Aşina olunan kod kalıplarını yeniden kullanın
  • Tutarlı kod kalıpları korunursa okunabilirlik artar
  • Yeni yaklaşımlar yerine mevcut ve aşina olunan kalıpları önceliklendirin

Kod okunabilirliğini artıran 8 kalıp

1. Satır/operatör/operand sayısını azaltın – küçük fonksiyonlar ve az sayıda değişken okunabilirliği artırır
2. Yeni yaklaşımlardan kaçının – kod tabanında aşina olunan kalıpları koruyun
3. Gruplandırma – uzun fonksiyon zincirleri, yineleyiciler vb. yardımcı fonksiyonlara ayrılmalı
4. Koşul ifadelerini sadeleştirin – koşullar kısa tutulmalı ve mantıksal operatör karışımı en aza indirilmeli
5. goto kullanımını en aza indirin – gerekirse yalnızca hata işlemede sınırlı biçimde kullanın
6. İç içeliği azaltın – iç içe geçmiş mantığı azaltın, gerekirse fonksiyonlara bölün
7. Açık değişken adları kullanın – belirgin ve çakışmayan değişken adları tercih edin
8. Değişken yaşam süresini kısaltın – fonksiyon içinde kısa tutun ve fonksiyon sınırlarını aşmasına izin vermeyin

Sonuç

• Kod okunabilirliği, kod kalitesinin önemli bir unsurudur
• Halstead ve Cognitive Complexity, okunabilirlik sorunlarını sayısallaştırıp iyileştirme yönü gösterebilir
• Kısa ve açık kod yazmak, bakımını kolaylaştırır ve hata olasılığını azaltır
• En iyi kod yazımı, sadeliği, tutarlılığı ve açıklığı önceliklendirmektir

[GN⁺]

Hacker News yorumu

• map, reduce, filter gibi fonksiyonel programlama yapılarını zincirlemek özlüdür, ancak uzun zincirler okunabilirliğe zarar verme eğilimindedir

  • Bunun makalede ima edilen şey olmadığını düşünüyorum
  • Bu, alışık olunmadığı için kötü olduğunu söyleyen genel bir şikayet gibi geliyor
  • Biraz alışınca, diğer yöntemlere göre okuyup yazması daha kolay oluyor
  • Fonksiyonel programlamanın temellerini öğrenmek önemli
  • Monad'ları açıklamaya gerek yok, ama en azından map ve filter'ı rastgele kötülemeyecek kadar aşina olunmalı

• İyi kodun önemli bir yönü niteliksel ve edebidir

  • Bu, matematiksel bir düşünce yapısına sahip programcılar ve akademisyenler için rahatsız edici olabilir
  • Dostoyevski'yi de Wodehouse'u da severim, ama yazıları çok farklıdır
  • Bir kod tabanının stilini anlamak zaman alır

• Kod okurken en yorucu sorun değişkenliktir

  • Bir değişkeni yalnızca bir kez "sabitleyebilme" yeteneği büyük bir nimettir
  • Bir metodu anlama süreci %0'dan %100'e tekdüze biçimde artmalıdır
  • GOTO'ların zararlı olmasının nedeni, değişken durumlarını takip etmenin zor olmasıdır

• Küçük fonksiyonlar ve az sayıda değişken genellikle daha kolay okunur

  • "Okunabilirlik" odağı mikro okunabilirliğe fazla kaymış durumda
  • Bu da kodun gereğinden fazla parçalanmasına yol açıyor
  • APL ailesi dilleri bunun karşı ucunda yer alıyor

• TypeScript kodu okumayı zorlaştırıyor

  • Veri modeli "atomik" kaldığında sorun olmuyor
  • Tip çıkarımına güvenildiğinde alanları özgün konumlarına kadar izlemek zorlaşıyor

• getOddness4 fonksiyonu asimetri yaratıyor

  • getOddness2 fonksiyonu simetrik bir seçim sunuyor

• Makale ilginç ama tatmin edici değil

  • Dile özgü operatörler veya sözdizimsel şeker kullanımından kaçınılması gerektiği görüşüne katılmıyorum
  • map, reduce, filter gibi yapılar doğru kullanıldığında diğer operatörlerin yerini alıyor ve "hacmi" azaltıyor

• Okunabilirliği tanımlamaya yönelik çaba övgüye değer

  • Birçok kişi üzerinde test yapılarak okunabilirliğin gerçek boyutları bulunabilir

• Kod karmaşıklığı sözdizim ağacının boyutuyla ifade edilir

  • Yerel karmaşıklık azaltımının toplam karmaşıklık üzerinde büyük bir etkisi yoktur

• Uzun fonksiyon zincirlerini veya callback'leri küçük gruplara ayırmak ve iyi adlandırılmış değişkenler kullanmak daha iyidir

  • Her iki sürüm de verimlilik açısından aynıdır
  • Fark derleyicidedir