Okunabilir kod için isimlendirme ve fonksiyon yazma kuralları

Kodu bir kez yazıyoruz ama defalarca okuyoruz. Altı ay sonra kendi kodunu anlamakta zorlanıyorsan, aşağıdaki kurallar işini kolaylaştırır. Hangi dili kullandığın fark etmez.

İsimlendirme

İsim, "ne" olduğunu söylesin; "nasıl" yapıldığını değil.

# Kötü
d = 86400
lst = get_data()

# İyi
SECONDS_PER_DAY = 86400
active_users = fetch_active_users()

• Boolean değişkenler soru gibi okunsun: is_active, has_permission, can_edit.
• Fonksiyonlar fiille başlasın: calculate_total(), send_invoice().
• Kısaltmadan kaçın. usrMgr yerine userManager. Editörün otomatik tamamlıyor, uzun isim maliyetsiz.
• Aynı kavrama tek isim ver. Bir yerde customer, başka yerde client, öbüründe buyer dersen okuyan üç farklı şey sanır.

Fonksiyonlar

Bir fonksiyon tek bir iş yapsın. Adını koyarken "ve" kelimesini kullanmak zorunda kalıyorsan (validateAndSaveAndNotify) bölme zamanı gelmiştir.

Erken dönüşle iç içe if'leri azalt:

// Kötü
function discount(user) {
  if (user) {
    if (user.isMember) {
      if (user.orders > 10) {
        return 0.2;
      }
    }
  }
  return 0;
}

// İyi
function discount(user) {
  if (!user || !user.isMember) return 0;
  if (user.orders <= 10) return 0;
  return 0.2;
}

Parametre sayısını düşük tut. Dört-beş parametreyi geçince bir nesne/yapı içinde toplamayı düşün.

Boolean parametrelerden kaçın. render(true) ne anlama geliyor? renderCompact() ve renderFull() diye iki fonksiyon çoğu zaman daha açık.

Yorumlar

• Kodun ne yaptığını değil, neden öyle yapıldığını yaz.
• Yorumla açıklamak zorunda kaldığın bir bloğu, iyi isimli bir fonksiyona taşımak genelde daha iyidir.
• Eski kodu yorum satırı olarak bırakma; Git zaten geçmişi tutuyor.

Son söz

Bu kurallar dogma değil. Ekipteki ortak stil, tek başına doğru bulduğun stilden daha değerlidir; bir linter/formatter (ESLint, Prettier, PHP-CS-Fixer, Black vb.) kurup tartışmayı araca bırakmak en sağlıklısı.

Sizin ekibinizde vazgeçilmez saydığınız bir kural var mı?