Ürün Odaklı Ekipler İçin Sade Kod İnceleme Kültürü

Büyük bir pull request'i açtığınızda yorumların nereden geleceğini tahmin etmek kolaydır: ilk gün kimse bakmaz, üçüncü gün on dört yorum düşer, bunların yarısı biçimlendirme üzerine, dördüncüsü ise bir dönem önceki bir kararın yeniden tartışılmasıdır. Yazan kişi yorgunluk ve savunma ile döner. İnceleyen kişi de yorgunluk ve biraz sinirle yazar. Sonuç, kodun kalitesinden çok ilişkilerin zarar gördüğü bir süreçtir.

Büyük pull request'ler yalnızca gözden geçirmeyi zorlaştırmaz; aynı zamanda geri bildirimin kişiselleşmesine yol açar. İnceleme ne kadar uzarsa, yorumlar o kadar sertleşir. Bu metinde, kod incelemesini bir savunma mekanizması olmaktan çıkarıp ortak anlayış üreten bir pratiğe dönüştüren küçük alışkanlıkları anlatacağım.

Kod incelemesi ne için var?

Kod incelemesinin üç amacı vardır, ama çoğu ekip yalnızca birincisini hatırlar. Birincisi hataları yakalamaktır. İkincisi ekipteki bilgiyi yaymaktır: bir değişikliği inceleyen kişi, o bölgenin nasıl çalıştığını öğrenir. Üçüncüsü ortak standardı korumaktır: adlandırma, katmanlar arası sınırlar, test kapsamı.

Bu üç amaç birlikte düşünüldüğünde inceleme bir kapı bekçiliği gibi değil, bir öğrenme alanı gibi çalışır. Yorum yazmak bir hüküm vermek değil, bir soru sormaktır. Bu fark tonu da değiştirir.

İyi inceleme, kodu değil kararı tartışır.

Küçük ve tek amaçlı değişiklikler

Bir pull request tek bir şeyi yapıyorsa, tartışma da tek bir konuya odaklanır. Refactor ile davranış değişikliğini aynı PR'da birleştirmek, niyeti okunamaz hâle getirir. İnceleyen kişi hem yapının iyileştirildiğini hem de davranışın değiştiğini aynı anda değerlendirmek zorunda kalır ve ikisinden birini kaçırması kolaylaşır.

Pratikte şu kural işe yarar: bir PR'ı tek cümleyle anlatamıyorsanız, muhtemelen bölmeniz gerekiyor. Büyük bir değişikliği birkaç küçük adıma ayırmak, her adımın kendi testiyle birlikte gelmesini sağlar.

• 200 satırı geçen PR'ları bölmeyi varsayılan kabul edin; istisna gerektiğinde gerekçesini yazın.
• Refactor, yeniden adlandırma ve davranış değişikliğini ayrı commit ya da ayrı PR olarak tutun.
• Kendi değişikliğinizin yalnızca bir amacı olduğundan emin olun.

Açıklama, niyeti taşır

Kodun ne yaptığı diff'te görünür; neden yapıldığı görünmez. İnceleyen kişiye bu bağlamı vermek için PR açıklaması vardır. İyi bir açıklama, kodu okumadan da değişikliğin amacını anlatır.

Aşağıdaki şablon, çoğu ekip için yeterlidir. Her başlık en fazla birkaç cümle taşır.

Bu şablonun en değerli bölümü "Yaklaşım"dır. Alternatifleri yazmak, inceleyen kişinin aynı tartışmayı baştan açmasını engeller ve daha iyi bir öneri varsa erken ortaya çıkmasını sağlar.

Yorumun tonu

"Burada hata var" cümlesi bir hüküm verir. "Şu senaryoda ne olur?" sorusu ise birlikte düşünmeyi davet eder. İkisi aynı tespiti taşıyabilir, ama ilki savunma üretir, ikincisi çoğu zaman daha derin bir kontrol sağlar. Yazan kişi soruya cevap verdiğinde kendi kodunu da yeniden okur.

Yorumların üç özelliği olması işe yarar: somut olmaları, neden önemli olduğunu söylemeleri ve bir öneri içermeleri. Bir yorum yalnızca "bu kötü" diyorsa, yazan kişi ne yapacağını bilemez.

Yorum: Bu döngü her istekte tüm yazıları yüklüyor. Kullanıcı sayısı artarsa
sayfa yavaşlar. Sayfalama eklenebilir mi, yoksa bu liste bilerek küçük mü tutuluyor?

Bu örnekte yorum bir soru, bir neden ve bir alternatif barındırıyor. Yazan kişi buna karşı bir argüman geliştirebilir, ama konuşma kişiye değil koda yönelmiş olur.

Neye önce bakılmalı?

Her değişikliğin tamamını aynı derinlikte okumak gerekmez. Bir inceleme sırası belirlemek, dikkatin doğru yere gitmesini sağlar. Bu sıra, hataların en pahalı olduğu yerden başlar.

1. Veri kaybına ya da güvenlik açığına yol açabilecek kısımlar: yetkilendirme, doğrulama, veritabanı yazmaları.
2. Sınırlar: yeni bir dış servis, yeni bir API alanı, bir modelin sorumluluğunun değişmesi.
3. Testler: yeni davranış için test var mı, test gerçekten başarısız olabilir mi?
4. Adlandırma ve okunabilirlik.
5. Biçimlendirme. Bu adım mümkünse otomatiğe bırakılmalıdır.

Son madde önemli. Biçimlendirme tartışmaları çoğu zaman en uzun yorum zincirlerini üretir ama en az değer taşır. Bir kod biçimleyicisi ve kurallı bir yapılandırma bu tartışmayı tamamen ortadan kaldırır; inceleme, yalnızca anlamı ilgilendiren konulara odaklanır.

Otomasyon ile insan dikkatini ayırmak

İnceleme sürecinin bir kısmı makinelere ait olmalıdır. Biçimlendirme, statik analiz, test çalıştırma ve bağımlılık kontrolleri her PR'da otomatik olarak yapılmalıdır. Bunlar kırmızıysa değişiklik zaten incelemeye hazır değildir.

Otomasyonun bir sınırı da vardır. Bir test geçiyorsa, o testin doğru şeyi kontrol ettiği anlamına gelmez. İnceleyen kişinin işi, testlerin gerçekten bir davranışı koruyup korumadığını sorgulamaktır. Bu nedenle yeni bir test yazıldığında, onu bilerek bozup başarısız olduğunu görmek iyi bir alışkanlıktır.

Ritim ve sorumluluk

Kod incelemesi, işin geri kalanından ayrı bir görev gibi düşünüldüğünde ihmal edilir. Bunu önlemek için ekipte net bir ritim gerekir: her gün belirli bir zamanda bekleyen PR'lara bakmak, ilk yanıt süresi için bir hedef koymak ve incelemeyi günlük işin bir parçası saymak.

İnceleyen kişiyi sık sık aynı kişi yapmak, bilgiyi tek bir yerde toplar ve bir süre sonra o kişi darboğaz olur. Dönüşümlü inceleme, bilgiyi yayar ve ekibin herkesi bir noktada sorgulayabilmesini sağlar.

• Her PR için en az bir, mümkünse iki inceleyici belirleyin.
• Yazan kişi, incelemeyi yanıtlamadan değişikliği birleştirmesin.
• Uzun süren tartışmaları yazı üzerinden değil, kısa bir görüşmeyle kapatın.

Ölçmek ve yanlış ölçmemek

İnceleme sürecini ölçmek cazip olabilir: kaç yorum yazıldı, kaç tur sürdü, ne kadar sürede onaylandı. Ama yorum sayısı kaliteyi göstermez. Çok yorum, çok dikkat anlamına da gelebilir; çok az yorum ise bir sorunun olmadığı anlamına değil, incelemenin yüzeysel kaldığı anlamına gelebilir.

Daha faydalı göstergeler, değişikliğin ne kadar sürede yayına girdiği ve yayına giden hataların ne sıklıkta incelemeden kaçtığıdır. Bunları suçlamak için değil, süreci iyileştirmek için kullanın.

İncelemeyi kendi makinenizde denemek

Diff'i yalnızca okumak, bir değişikliğin çalışıp çalışmadığını söylemez. Özellikle davranış değişikliklerinde, incelemeyi yerelde yapmak çok daha güvenilir bir sonuç verir. Dalı çekin, testleri çalıştırın ve değişikliğin etkilediği ekranı kendiniz açın. Bu yalnızca beş dakika sürer, ama birçok hatayı yayına girmeden yakalar.

git fetch origin
git switch arama-filtresi-duzeltme
php artisan test --compact tests/Feature/BlogTest.php
npm run build

Bu adımların yalnızca ilgili testlerle sınırlı olması, zamanı verimli kullanmanın bir yoludur. Tüm test paketi her inceleme için gerekli olmayabilir; ama değişikliğin dokunduğu alanın testlerinin tamamının geçtiğini görmek, yazan kişiye ve inceleyen kişiye güven verir.

Reddetmek ve geri çekmek

Her yorum bir engel değildir. Bir inceleme yanıtının üç durumu olabilir: onay, yorumlarla onay ve değişiklik isteme. Bu ayrımı net yapmak, yazan kişinin neyi düzeltmesi gerektiğini bilmesini sağlar. Küçük bir isimlendirme önerisi için değişiklik istemek, bir güvenlik açığı için istemekten farklı bir ağırlık taşır.

Yorumları etiketlemek bu ayrımı görünür kılar. Bloklayıcı yorumlar için bir etiket, küçük öneriler için başka bir etiket kullanılabilir. Bazı ekipler küçük öneriler için "nit" kelimesini kullanır; bu, yazan kişiye bu yorumun reddedilmek için olmadığını söyler.

• Bloklayıcı: güvenlik, veri kaybı, yanlış davranış.
• Öneri: daha okunaklı ya da daha basit bir yol.
• Küçük not: isim, boşluk, yorum metni.

Bir değişikliği geri çekmek de bir seçenektir. Bir PR'ın kapsamı tartışma içinde büyüyorsa, yazan kişinin onu bölmesi ya da yeniden planlaması daha sağlıklı olabilir. Bu bir başarısızlık değil, ekibin ortak bir karar vermesi için bir fırsattır.

Sahiplik ve ortak kod

Bir dosyanın kimin sorumluluğunda olduğunu bilmek, incelemenin kime gitmesi gerektiğini belirler. Bu bilgi, bazı ekiplerde bir kod sahiplik dosyasıyla tutulur ve değişiklik yapılan alanın sahipleri otomatik olarak incelemeye çağrılır. Bu düzen, uzmanlığın doğru yerde kullanılmasını sağlar.

Ama sahiplik, kimsenin başka bir alana dokunamayacağı anlamına gelmemelidir. Ortak kodun her parçası, herkes tarafından değiştirilebilir olmalıdır; sahiplik yalnızca incelemenin hangi kişiye yönleneceğini belirler. Bu ayrımı net tutmak, insanlar arasında gereksiz engeller oluşmasını önler.

Yeni katılanları incelemek

Ekibe yeni katılan birinin ilk değişikliklerini incelemek, bir öğretim anıdır. Bu incelemelerde en çok kaçınılması gereken şey, bilginin eksikliğini kişiye yüklemektir. "Bunu neden bilmiyorsun?" yerine "Bu kısım nasıl çalışıyor, birlikte bakabilir miyiz?" demek, hem soruyu hem de öğrenmeyi kolaylaştırır.

İlk değişikliklerde bir ayrıntı üzerinde yoğunlaşmak yerine, bir kez birlikte bir örnek üzerinde ilerlemek daha etkilidir. Yazan kişi bir kalıbı öğrendiğinde, sonraki incelemelerde aynı yorumları yazmanız gerekmez. Bu, inceleme süresini kısaltır ve ekibe yeni bir üye kazandırır.

İncelemede sık yakalanan hatalar

Bazı hatalar, bir inceleme sürecinde tekrar tekrar ortaya çıkar. Bunları bir kontrol listesi olarak tutmak, incelemenin kalitesini ortak bir seviyeye çıkarır. Her ekibin kendi listesi olabilir, ama birkaç madde neredeyse her yerde görülür.

Bu tablodaki sorular, bir değişikliği okurken zihninizde tutmanız için iyi bir yardımcıdır. Her PR için hepsini sormak gerekmez; ama değişikliğin türüne göre ilgili olanları sormak, yakalanabilecek hataları önemli ölçüde azaltır.

Kendi inceleme alışkanlığınızı izlemek

İnceleme yapan kişi de gelişebilir. Her hafta yazdığınız yorumlara bakın ve tekrar eden temaları not edin. Bir konuda sürekli yorum yazıyorsanız, bu ekibin kendisine bir kural ya da araç gerektiğinin işareti olabilir. Örneğin sürekli isimlendirme yorumu yazıyorsanız, bir adlandırma rehberi yazmak daha verimli olur.

Ayrıca kendi yorumlarınızın tonunu da düşünün. Kısa ve sert yorumlar, çoğu zaman bir soruya dönüştürülebilir. Yazan kişinin yanıt vermesi için bir neden ve bir yol sunmak, tartışmayı kişiselleştirmeden ilerletir.

Sonuç

Kod incelemesi, bir ekibin birbirini nasıl düşündüğünü gösteren en açık aynadır. Küçük değişiklikler, açık açıklamalar, soru soran yorumlar ve otomasyonla ayrılmış dikkat, bu aynanın daha az sert görünmesini sağlar.

Ekibinizde bu alışkanlıkları başlatmak için kısa bir liste:

• Bu hafta açılan PR'ların boyutunu ve açıklamalarını birlikte gözden geçirin.
• Biçimlendirme kurallarını otomasyona bağlayın ve tartışmayı bitirin.
• Her yoruma bir soru ya da öneri eklemeyi norm hâline getirin.
• Haftada bir, en uzun süren incelemeyi birlikte inceleyin ve nerede takıldığınızı konuşun.