Code review: iyi yorum nasıl yazılır, eleştiri nasıl alınır?

Ekipte bir pull request açtın ve ilk yorumu bekliyorsun. Ya da bir arkadaşının PR'ını açtın ve ne yazacağını bilmiyorsun. İkisi de öğrenilebilen beceriler. Code review'un amacı hata avlamak ya da kimin daha iyi kod yazdığını göstermek değil: kodun ekibe ait olmasını, bir kişinin kafasında kalmamasını sağlamak. Google'ın mühendislik pratiklerindeki ölçüt de bunu söylüyor: bir değişiklik kusursuz olmasa bile kod tabanının genel sağlığını iyileştiriyorsa onaylanmalı.

Önce PR'ı review'a hazır hâle getir

İyi bir review, iyi hazırlanmış bir PR ile başlar. Göndermeden önce:

• Küçük tut. Tek bir işi yapan, birkaç yüz satırı geçmeyen bir PR'ı insanlar dikkatle okur. Bin satırlık bir PR'a ise "LGTM" yazılır ve geçilir. Büyük bir işi parçalara böl.
• Açıklama yaz. Ne değişti, neden değişti, nasıl test ettin? Arayüz değiştiyse önce/sonra ekran görüntüsü ekle. İlgili issue'yu bağla.
• Kendi PR'ını önce sen oku. GitHub'daki "Files changed" sekmesinde kendi kodunu baştan sona geç. Unuttuğun bir console.log, yorum satırına alınmış eski kod ya da yanlışlıkla eklenen bir dosya genelde burada yakalanır.
• Otomatik kontroller geçsin. Testler ve linter kırmızıysa insanı onları okumaya davet etme.

Review yaparken neye bakılır?

Sırayla, büyükten küçüğe:

1. Doğru mu? Kod, PR'ın söylediği şeyi gerçekten yapıyor mu? Boş liste, ağ hatası, yetkisiz kullanıcı gibi kenar durumlarda ne oluyor?
2. Tasarım: Bu kod doğru yerde mi? Var olan bir yardımcı fonksiyonun aynısı yeniden mi yazılmış?
3. Anlaşılır mı? Altı ay sonra bu kodu ilk kez gören biri ne yaptığını anlayabilir mi? Adlandırmalar açık mı?
4. Testler: Değişikliği doğrulayan bir test var mı? Test gerçekten bir şeyi kontrol ediyor mu?
5. Biçim: En son. Boşluk, sıralama ve isimlendirme kuralları için ekip bir formatlayıcı ve linter kullanıyorsa insanın buna yorum yazması gerekmez.

İyi bir yorum nasıl yazılır?

Yorumun hedefi kod, kişi değil. Aynı içerik iki farklı biçimde yazılabilir:

• Kötü: "Bu yanlış."
• İyi: "Liste boş geldiğinde items[0] hata veriyor gibi. Başta bir boş kontrol ekleyebilir miyiz?"

• Kötü: "Neden böyle yaptın?"
• İyi: "Burada map yerine döngü kullanmanın bir sebebi var mı? Yoksa map biraz daha okunur olabilir."

İşe yarayan birkaç alışkanlık:

• Neden'ini söyle. "Şunu değiştir" yerine "şu yüzden şunu öneriyorum". Neden'i bilen kişi bir sonraki sefer aynı şeyi kendisi düşünür.
• Önem derecesini belirt. Her yorum aynı ağırlıkta değil. Küçük önerilerin başına "Küçük:" ya da "nit:" yazmak, yazara hangilerinin birleştirmeyi engellediğini, hangilerinin isteğe bağlı olduğunu söyler.
• Soru sor. Bir şeyi anlamadıysan bu kodun anlaşılmaz olduğunun işareti olabilir. "Bu satır ne yapıyor?" meşru bir yorum.
• İyi olanı da yaz. Akıllıca çözülmüş bir yeri fark ettiysen söyle. Review yalnızca kusur listesi olmak zorunda değil.
• Hızlı ol. Bekleyen bir PR, yazarın kafasında açık kalan bir iş demek. Günün içinde bir kez dönmek bile çok şey değiştirir.

Eleştiri nasıl alınır?

Kendi koduna yorum gelmesi, özellikle ilk zamanlarda insanın kendine yorum gelmesi gibi hissettirebilir. Değil. Birkaç öneri:

• Kod sen değilsin. Yorum kodu daha iyi hâle getirmek için yazıldı. İyi bir ekipte en çok yorum alan kod genelde en çok önemsenen koddur.
• Her yoruma cevap ver. Değişikliği yaptıysan "düzelttim" yaz ya da commit'i bağla. Katılmıyorsan sebebini kısaca açıkla. Sessiz kalmak, yorumu yazanın tekrar sorması demek.
• Tartışma uzarsa yüz yüze geç. Bir yorumun altında beşinci mesaj yazılıyorsa iki dakikalık bir konuşma muhtemelen daha hızlı çözer. Sonucu yine yorumun altına yaz ki ekip görsün.
• Aynı yorumu iki kez alma. Bir kural öğrendiysen bir dahaki PR'da kendin uygula. Bu, review'da en hızlı ilerleme yolu.

Küçük bir ekip için başlangıç kuralları

Üç dört kişilik bir öğrenci projesinde şu kurallar iyi bir başlangıç:

1. Kimse doğrudan main'e push etmiyor; her değişiklik bir PR.
2. Her PR'a en az bir kişi bakıyor ve onaylıyor.
3. PR açan kişi açıklama yazıyor ve kendi kodunu önce kendisi okuyor.
4. Review'lar 24 saat içinde yapılıyor.
5. Biçimle ilgili tartışmalar formatlayıcıya bırakılıyor.

GitHub'da main branch'i için bir koruma kuralı açarak ilk iki maddeyi zorunlu da yapabilirsin. Branch, issue ve pull request akışını adım adım görmek istersen Git pull request yazımıza bakabilirsin.

Gerçek bir projede review alıp vermek istiyorsan re:make'teki ekip projeleri tam bunun için var. Her pazar 15.00'te Buca'da buluşuyoruz; üye olmadan da gelebilirsin. Yeri ve saati burada.