PR'ı açın, inceleyiciniz henüz onunla tanışmadı
Geçenlerde büyük bir pull request inceledim. Kod yazımında yapay zekadan yardım alınmıştı. Üç farklı özelliğin kullandığı bir modülü değiştirmişti. Açıklama sadece tek bir cümleden ibaretti. Dosyanın adını belirtmişti ama değişikliğin nedenini yazmamıştı.
İncelemeye başlayabilmek için değişiklikleri haritalandırmakla on beş dakika harcadım. Amacı bulmam gerekiyordu. Riskleri tespit etmem gerekiyordu. Önemli dosyaları gürültüden ayırmam gerekiyordu.
Bunu daha önce başka birine de yapmış olduğumu fark ettim.
Kod yazarken tüm bağlamı (context) beraberinizde taşırsınız. Bir modülü neden böldüğünüzü bilirsiniz. İlk önce neyi denediğinizi bilirsiniz. Hangi kısımlardan emin olmadığınızı bilirsiniz.
Çoğu insan açıklamaları kendisi için yazar. "Service layer refactor edildi" veya "Auth modülü düzeltildi" gibi şeyler yazarlar. Bunlar, bağlamı zaten bilen kişiler için yazılmış açıklamalardır.
İyi bir açıklama, hiçbir şey bilmeyen kişi içindir.
Açıklama sadece bir özet değildir. Bir testtir. Eğer çalışmanızı açıklayamıyorsanız, çalışmanız henüz hazır değildir.
Artık her önemli (non-trivial) PR için altı bölümlü bir yapı kullanıyorum:
• Amaç (Intent): Bu PR'ın neden var olduğunu ve hangi sorunu çözdüğünü açıklayın. Eğer bunu yazamıyorsanız durun. PR hazır değildir. • Büyük değişiklikler (Major changes): Mimarîyi veya mevcut davranışı etkileyen kararları listeleyin. • Küçük değişiklikler (Minor changes): Temizlikleri ve yeniden adlandırmaları listeleyin. Bunları yapısal değişikliklerden ayrı tutun. • Etki (Impact): Bu değişikliğin dokunduğu sistemleri listeleyin. Etki alanının (blast radius) bir haritasını sunun. • Kanıt (Evidence): Neleri çalıştırdığınızı ve hangi testlerden geçtiğinizi listeleyin. İşi yaptığınıza dair kanıt gösterin. • Belirsizlikler (Uncertainties): Nelerden emin olmadığınızı belirtin.
Belirsizliği kabul ettiğinizde, incelemeciye yardımcı olursunuz. Nereye dikkatli bakmaları gerektiğini bilirler. Sorunsuz çalışan kısımlarda vakit kaybetmezler.
Eğer belirsizliklerinizi isimlendiremiyorsanız, kodunuz üzerine yeterince derin düşünmemişsiniz demektir.
Açıklama, bir PR'ın açılıp açılmaması gerektiğine karar vermeden önceki son adımdır.
Amacınızı anlayan bir incelemeci, vaktini zor sorulara ayırır. Amac
Kaynak: https://dev.to/jeelvankhede/open-the-pr-your-reviewer-has-not-met-yet-4gfe
İsteğe bağlı öğrenme topluluğu: https://t.me/GyaanSetuAi
PR'ı Açın, İnceleyicinizle Henüz Tanışmadınız
Bir Pull Request (PR) açmak için mükemmel anı beklemek, bir yazılımcının yapabileceği en büyük hatalardan biridir. "Sadece şu son özelliği bitireyim" veya "Önce şu küçük teknik borcu temizleyeyim" diye düşünürsünüz ve ne olduğunu anlamadan günler, hatta haftalar geçer.
O PR'ı nihayet açtığınızda, devasa bir kod dağı inşa etmiş olursunuz. Ve şimdi, inceleyicinizin bu dağı tırmanması gerekir.
İşte "hazır" olmasalar bile PR'larınızı neden daha erken açmanız gerektiğinin nedenleri:
- Erken Geri Bildirim: Yanlış yöne gidiyor olabilirsiniz. 500 satır kod yazdıktan ziyade, 50 satır kod yazmışken rotayı değiştirmek çok daha kolaydır.
- Bilgi Paylaşımı: İnceleyiciniz sorunu çözmek için daha iyi bir yol biliyor olabilir. Mevcut bir yardımcı fonksiyonu (utility) veya işinizi basitleştirecek bir deseni (pattern) biliyor olabilirler.
- Azaltılmış Karmaşıklık: Küçük, kademeli PR'lar incelenmesi daha kolay olanlardır. Büyük, monolitik PR'lar göz korkutucudur ve genellikle yüzeysel incelemelere yol açar.
- Görünürlük: Ekibinize ne üzerinde çalıştığınızı gösterir. Siloların oluşmasını engeller ve herkesin süreçten haberdar kalmasını sağlar.
Mükemmelliği beklemeyin. PR'ı açın, geri bildirimi alın ve yineleyin. İnceleyiciniz (ve gelecekteki haliniz) size teşekkür edecek.