Kod tabanında isimlendirme: bir mimari mesele

Kod incelemelerinde en çok tartışılan şeylerden biri isimler. “Bu değişkene daha iyi bir isim bulalım”, “bu metot ismi yanlış bir beklenti yaratıyor.” Bu tartışmalar bazen stilistik bir alışkanlık gibi görünür — birileri mükemmeliyetçi davranıyor diye. Ama ben bu tartışmaların büyük çoğunluğunun aslında başka bir şeyle ilgili olduğunu düşünüyorum: tasarım.

Bir isim kolayca bulunamıyorsa çoğunlukla nesnenin veya metodun ne yaptığı belirsizdir. İsimlendirme sorunu, aslında tasarım sorunudur.

Kötü isim kötü tasarımın yüzeyi

Şu metot imzasını düşünün:

public function process(array $data): array

process ne yapıyor? $data ne içeriyor? Dönüş değeri ne? Hiçbirini bilmiyoruz. Kodu açıp okumak zorundayız.

Şimdi şunu düşünün: bu ismi düzeltmeye çalıştığınızda ne olur? “Sipariş verilerini işle” mi? Ama içinde kullanıcı doğrulaması da var. “Formu kaydet” mi? Ama veritabanına yazmıyor, sadece dönüştürüyor. “Form verisini sipariş modeline dönüştür” mi? Artık daha iyi ama belki validateAndTransformOrderData gibi bir şey çıkıyor — bu da ismin zaten bir uyarı verdiği anlamına geliyor: bu metot çok fazla iş yapıyor.

İsim bulunamıyorsa nesne veya metot muhtemelen tek sorumluluğa sahip değildir.

İsmin güçlü olduğunu nasıl anlarsınız

İyi bir ismin birkaç özelliği var:

Niyeti anlatır, implementasyonu değil. getUsersByActiveStatus değil, findActiveUsers. calculateAndReturnTotal değil, total(). İşin ne olduğunu söyleyin, nasıl yapıldığını değil.

Sürpriz yaratmaz. save() metodunu çağırdığınızda ne bekliyorsunuz? Veriyi kaydetmesini. Eğer bu metot aynı zamanda bir e-posta gönderiyorsa ya da bir loglama yapıyorsa — isim sizi hazırlamadı. Bu güven ihlali; küçük bir güven ihlali ama birikince kod tabanına güven azalıyor.

Alanın dilini konuşur. Bir fintech uygulamasında amount ve total farklı şeyler ifade edebilir. Bir e-ticaret sisteminde order ile cart aynı şey değildir. İsimlerin alanın (domain) dilinden gelmesi, kodun o alanı tanıyan biriyle konuşmayı kolaylaştırır.

Sınıf isimlerinde sık gördüğüm sorunlar

Manager, Handler, Helper, Util: Bunlar tehlike işaretleri. Bu isimler “bu sınıfın ne yaptığını tam bilmiyorum” demek. UserManager ne yapar? Her şeyi. PaymentHelper ne yapar? Bir şeyler. Bu sınıflar zamanla şişer çünkü herkes bir şeyi oraya koyabilir.

// Belirsiz
class PaymentHelper
{
    public function process($data) {}
    public function validate($data) {}
    public function format($amount) {}
    public function log($payment) {}
}

// Daha net — her sınıf bir sorumluluğa sahip
class PaymentProcessor
{
    public function charge(Money $amount, PaymentMethod $method): PaymentResult {}
}

class PaymentValidator
{
    public function validate(PaymentRequest $request): ValidationResult {}
}

Fiil-ağırlıklı sınıf isimleri: CreateOrder, ProcessPayment, SendEmail gibi sınıf isimleri genellikle bir action pattern veya command pattern uygulamasıdır. Bunlar kendi yerlerinde doğru; ama bütün sınıf isimleriniz fiil+nesne formundaysa aslında sadece bir büyük prosedürel kodu küçük parçalara bölmüş olabilirsiniz. Nesne yönelimli tasarım her zaman bu değildir.

Metodlarda isim ve imza uyumu

Metot ismi ile imzası uyumsuzsa bu da bir tasarım işareti:

// İsim "bul" diyor ama exception fırlatıyor — bu "bul ya da patlat"
public function findUser(int $id): User
{
    $user = $this->repository->find($id);
    if (!$user) {
        throw new UserNotFoundException($id);
    }
    return $user;
}

// Daha açık isimler
public function findUser(int $id): ?User  // null dönebilir
public function getUser(int $id): User    // yoksa exception — getX semantiği

Bu fark küçük görünüyor ama API tüketenlerin beklentisini şekillendiriyor. findUser çağıran biri null kontrolü yapar; getUser çağıran biri try-catch düşünür.

İsimlendirme bir kararın kaydıdır

Bir ismi değiştirdiğinizde bazen bir değişiklikten fazlasını yaptığınızı fark edersiniz. Belki sınıfı bölersiniz. Belki bir metodu taşırsınız. Belki bir soyutlama katmanı eklersiniz. İsim, tasarıma baktığınız bir ayna işlevi gördü.

Bu yüzden isimlendirmeyi “üslup” tartışması olarak görmüyorum. İsimlendirme tartışması çoğu zaman tasarım tartışmasıdır — ve bu tartışmayı erken yapmak, kodu yazdıktan aylar sonra yapmaktan çok daha ucuz.

İyi isimler kod tabanını kendi kendini anlatan bir şeye dönüştürür. Bu sürdürülebilir kod yazmanın sessiz ama kalıcı bileşenlerinden biridir.