Hata kaydı ve kod incelemesi (bug report, code review)

Merak sorusu

Emre ödeme hatasının izini bir saat içinde sürüyor: kullanıcı "Pay" düğmesine hızla iki kez basarsa ödeme iki kez alınıyor. Kaydı hızla yazıyor: "Payment not working. Please fix ASAP." Dublin'deki QA mühendisi Declan yarım saat sonra üç soruyla dönüyor: Hangi tarayıcıda? Hangi adımlarla? Ne olması gerekiyordu?

Öğleden sonra sıra incelemeye geliyor: Declan'ın ödeme akışını yeniden düzenleyen PR'ı Emre'nin onayını bekliyor. Kodda bir sorun görüyor ama İngilizce nasıl söyleyeceğini bilmiyor: "This is wrong" demek kaba geliyor, hiçbir şey söylememek ise yanlış. Başka bir şehirdeki biri bir hatayı hiç soru sormadan nasıl yeniden üretebilir, ve bir meslektaşın kodundaki sorun ona nasıl söylenir?

Anlatım

İyi bir hata kaydı: başkası yeniden üretebilmeli

Bir hata kaydının tek bir amacı vardır: onu okuyan biri, sana bir şey sormadan hatayı kendi bilgisayarında yeniden üretebilmeli. Emre'nin ilk kaydı bu yüzden işe yaramadı: ne olduğunu söylüyordu ama nasıl olduğunu söylemiyordu. Yazılım ekiplerinde iyi bir hata kaydı genellikle aynı parçalardan oluşur: açıklayıcı bir başlık, ortam bilgisi, adım adım yeniden üretme yolu, beklenen sonuç, gerçekleşen sonuç ve varsa ekran görüntüsü ya da log kaydı.

Başlık, hatanın ne olduğunu ve ne zaman olduğunu tek satırda söyler. "Payment not working" çok geniştir; hangi ödeme, ne zaman, nasıl çalışmıyor? Daha iyi bir başlık hatanın koşulunu da içerir.

Adımlar, beklenen ve gerçekleşen

Yeniden üretme adımları kısa, numaralı ve emir kipiyle yazılır, çünkü okura ne yapacağını söyler: "Log in as a test user", "Add any item to the basket", "Go to checkout", "Click Pay twice within one second". Her adım tek bir eylemdir ve okurun tahmin etmesine yer bırakmaz.

Adımların ardından iki kısa satır gelir. "Expected" ne olması gerektiğini, "Actual" ise gerçekte ne olduğunu söyler. Bu iki satır arasındaki fark, hatanın ta kendisidir.

Ortam bilgisi de unutulmamalıdır: hangi ortam, hangi tarayıcı ya da cihaz, hangi sürüm. Hatanın her seferinde mi yoksa ara sıra mı olduğu da yazılır: "Reproducible every time" ya da "Happens about one time in five." Ekiplerin çoğu ayrıca hatanın ne kadar ciddi olduğunu belirten bir alan kullanır; bu alanın adı ve seçenekleri ekibin kullandığı araca göre değişir.

Kod incelemesi: kod hakkında, kişi hakkında değil

Kod incelemesinde yazılan yorumlar kalıcıdır ve ekibin herkesi tarafından okunur. İyi bir yorumun ilk kuralı, kişiyi değil kodu konu almaktır. "You forgot to check for null" cümlesi, "This function doesn't check for null" cümlesinden daha suçlayıcı okunur. Aynı bilgiyi verir, ama birincisi bir kişiye, ikincisi bir satıra bakar.

İkinci kural, öneriyi bir soru ya da bir teklif olarak kurmaktır. "Change this" bir emirdir; "Could we move this check into the service layer?" bir tekliftir ve yazara düşünme alanı bırakır. Bir şeyin neden önerildiğini söylemek de yorumu güçlendirir: "…so that the same check isn't repeated in three places."

Önemli ile küçük ayrımı

Her yorum aynı ağırlıkta değildir. Bazı yorumlar birleştirmeden önce mutlaka düzeltilmesi gereken bir sorunu gösterir; bazıları ise yalnızca bir tercih ya da küçük bir biçim önerisidir. Birçok ekip küçük yorumların başına "nit:" yazar; bu, "nitpick", yani önemsiz bir ayrıntı anlamına gelir ve yazara bunun birleştirmeyi engellemediğini söyler: "nit: this variable name could be more specific." Yorumun engelleyici olup olmadığını açıkça söylemek de mümkündür: "Not blocking, but…"

İyi bir inceleme yalnızca sorunları göstermez; iyi yapılmış bir şeyi de söyler. "Nice, this is much easier to read now" gibi kısa bir cümle, eleştirilerin geri kalanının nasıl okunacağını değiştirir.

İncelemeye cevap vermek

PR'ın yazarı olduğunda da aynı dil işler. Haklı bir yoruma kısa bir kabul yeter: "Good catch, fixed in the latest commit." Katılmadığında gerekçe verilir ve kapı açık bırakılır: "I kept it here because the service layer doesn't have the session data. Happy to discuss if you see a better option."

Türkçe köprüsü

Türkçede bir meslektaşın işindeki hatayı yazılı olarak söylemek iki uca kayabilir: ya "Bir bakabilir misin acaba, belki ben yanlış anlıyorumdur" diye geri çekilinir ya da "Bu yanlış" deyip geçilir. İngilizce kod incelemesinde beklenen ton ikisinin arasındadır: sorun açıkça söylenir, ama kişiye değil koda yönelik ve bir gerekçeyle.

Hata kaydında ise Türkçe alışkanlık kısa ve aceleci bir notu yeterli sayabilir: "Ödeme çalışmıyor, acil." Aynı ofiste oturan bir ekip arkadaşı bunu sorarak tamamlayabilir. Farklı saat dilimlerinde çalışan bir ekipte ise her eksik bilgi bir soru, her soru da yarım günlük bir gecikme demektir. Ayrıntılı bir hata kaydı, aynı zamanda karşı tarafın zamanına gösterilen bir saygıdır.

Gerçek hayattan örnekler

Emre hata kaydını yeniden yazıyor: açıklayıcı bir başlık, ortam bilgisi, dört numaralı adım, beklenen ve gerçekleşen sonuç, bir de ekran kaydı. Declan bu kez soru sormuyor; on dakika sonra kaydın altına tek bir satır yazıyor: "Reproduced. Thanks for the clear steps."

Ardından Emre, Declan'ın PR'ına üç yorum bırakıyor. Birincisi, çift tıklama sorununu soran ve bir çözüm öneren engelleyici bir yorum. İkincisi "nit:" ile başlayan bir değişken adı önerisi. Üçüncüsü kısa bir övgü: "Nice refactor of the checkout flow." Declan iki saat sonra cevap veriyor: "Good catch on the double click, fixed. Renamed the variable too." Lena toplantıda bu incelemeden söz ediyor: "That's the kind of review we want."

Sık yapılan hata

Bir başka sık sorun da her küçük biçim önerisini engelleyici bir sorunmuş gibi yazmaktır. Küçük yorumları "nit:" ile işaretlemek, yazarın neyin gerçekten önemli olduğunu görmesini sağlar.

Mini alıştırma

1. İyi bir hata kaydının tek amacı nedir?
2. Yeniden üretme adımları hangi kiple yazılır ve neden?
3. "Expected" ve "Actual" satırları neyi gösterir?
4. "You forgot to check for null" yorumu nasıl daha iyi yazılabilir?
5. Bir inceleme yorumunun başındaki "nit:" ne anlama gelir?

Cevaplar

1. Okuyan birinin, soru sormadan hatayı kendi bilgisayarında yeniden üretebilmesi.
2. Emir kipiyle; okura ne yapacağını tek tek söyler.
3. Ne olması gerektiğini ve gerçekte ne olduğunu; aradaki fark hatanın kendisidir.
4. Kodu konu alarak ve gerekirse bir soru ya da teklif olarak: "This function doesn't check for null. Could we add a check here?"
5. Önemsiz bir ayrıntı, yani birleştirmeyi engellemeyen küçük bir öneri.

Sesli tekrar görevi

Sonra bir kod incelemesinde bırakacağın üç yorumu yüksek sesle kur: soru biçiminde engelleyici bir yorum, "nit:" ile başlayan küçük bir öneri ve kısa bir övgü. En sonda kendi PR'ına gelen bir yoruma cevap ver: "Good catch, fixed in the latest commit."

Özet kartı

1. Hata kaydı başkasının hatayı yeniden üretebilmesi içindir.
2. Parçalar: koşulu söyleyen başlık, ortam, numaralı adımlar, Expected, Actual, ek kanıt.
3. Adımlar emir kipiyle ve her biri tek eylem.
4. İnceleme yorumu kodu konu alır, kişiyi değil; öneri soru ya da teklif olarak, gerekçesiyle.
5. Küçük yorumlar nit: ile, engellemeyenler Not blocking, but… ile; iyi yapılanı da söyle.
6. Cevap: Good catch, fixed; katılmadığında gerekçe ve Happy to discuss.

Sonraki derse köprü

Hata düzeltildi, ama Lena bir şeye dikkat çekiyor: ödeme servisinin nasıl çalıştığını anlatan bir belge yok ve yeni gelen her geliştirici aynı soruları soruyor. Emre'den servisin kısa bir README'sini ve bir API açıklamasını yazmasını istiyor. Teknik dokümantasyonun dili sıradaki ders.