Bir PR açıklamasını okurken daha ilk satırda “tamam, bu kişi işi biliyor” dedirten şey aslında kod değil… metnin kendisi. Açık konuşayım, yıllardır ekip içi review süreçlerinde en çok vakit yediren şeylerden biri de şu oldu: kod gayet düzgün, ama açıklama sanki müşteri hizmetleri e-postası gibi yazılmış. İşin aslı şu ki, PR description küçük bir metin gibi görünür; pratikte ise ekip içi iletişimin omurgasıdır.
Dürüst olmak gerekirse, Geçen yıl Ekim 2024’te İstanbul’da bir fintech ekibiyle yaptığım kısa danışmanlıkta bunu birebir gördüm. Geliştirici arkadaşın kodu tertemizdi ama açıklama “Please kindly review this PR” diye başlıyordu. Review yapan kıdemli mühendis bana dönüp “Bu bir iş başvurusu mu, yoksa teknik not mu?” diye sormuştu. Haklıydı. Bir başka örnek de 2023 yazında Ankara’daki bir SaaS startup’ında yaşandı; aynı değişiklik iki farklı kişinin elinden geçti ve biri tek paragrafta neyi neden yaptığını anlatınca merge süresi yarıya indi.
Neden PR açıklaması önemli?
Bakın şimdi, çoğu ekip PR’ı sadece “değişiklik listesi” sanıyor. Değil. PR açıklaması; niyet, bağlam ve risk notudur — yani kodun arkasındaki mantığı görünür yapar. Mesela uzaktan çalışan ekiplerde ya da farklı ülkelerden gelen geliştiricilerle çalışırken bu metin adeta küçük bir köprü işlevi görüyor; olmadığında ne olduğunu anlayabiliyorsunuz. Neden olduğunu anlayamıyorsunuz, ki bu ikincisi çok daha kritik.
Benim gözlemim şu. Kod inceleyen kişi genelde üç şeye bakıyor: ne değişti, neden değişti, kırılma riski var mı? Bu üç soruya cevap veren PR’lar hem daha hızlı onay alıyor hem de tartışmayı gereksiz yere uzatmıyor. Hani bazen diff’e bakarsınız ama kafanızda eksik parça kalır ya… işte o parçayı açıklama tamamlıyor (buna dikkat edin). Tam da bu yüzden.
PR açıklaması bir mektup değil; teknik kararın kısa hikâyesi.
Sorunlu kalıplar ve neden kulağa tuhaf geliyorlar
İlk büyük hata aşırı kibar olmak. Mesela “Please kindly review this PR” cümlesi kötü niyetli değil tabii ama native kulağa fazla resmi geliyor; hatta biraz müşteri destek maili hissi veriyor. Geliştirme dünyasında beklenti daha doğrudan: ne yapılmış, hangi problem çözülmüş, hangi risk kalmış. Bu kadar.
İkinci klasik hata belirsizliği yumuşatmak için üst üste kaçamak kelime yığmak (buna dikkat edin). “I think maybe we should consider possibly…” diye başlayan cümleler okuyana güven vermiyor çünkü fikir netleşmiyor; bir noktadan sonra insan şunu düşünüyor: Tam olarak önerin ne? Neyse, bu konuda sayfalar dolusu şey yazılabilir ama asıl mesele şu — tereddüt okuyanda değil, yazanda olmalı.
Doğrusu, Bir de emir kipine kayan yorumlar var. Mesela Türkçe ana dil olan kişiler İngilizce feedback verirken fark etmeden sertleşebiliyor; “You should change this variable name” demek yerine davranışı tarif etmek çok daha doğal duruyor,. Kodla ilgili yorum yapıyorsanız karşı tarafın “ders alıyorum” değil “bu konuya birlikte bakıyoruz” hissi alması gerekiyor. Daha fazla bilgi için Honor Win 2 Sızdı: Batarya ve Ekranda Büyük Oyun yazımıza bakabilirsiniz.
| Kötü kalıp | Neden zorlayıcı? | Daha doğal versiyon |
|---|---|---|
| Please kindly review this PR | Aşırı resmî, e-posta gibi duruyor | Please take a look when you have a chance |
| I think maybe we should possibly… | Kararsızlık yaratıyor | I’d suggest using… |
| You should change this variable name | Sert ve öğretici tonda | Nit: userCount reads better than cnt |
| fixed bug / update code / add changes | Neyi değiştirdiği belli değil | fix(auth): prevent session expiry during active requests |
The What/Why/How düzeni neden işe yarıyor?
Bölümü kısa tut, mesajı net ver
Sihir yok burada aslında. Mesele düşünceyi bölmekte yatıyor. “What” kısmı ne yaptığını söyler; “Why” bunun sebebini açıklar — asıl değer zaten orada çıkıyor, diff’e bakarak bunu anlamak çoğu zaman mümkün değil (ciddiyim). “How” ise uygulama detayını verir. Özellikle büyük diff’lerde, onlarca dosyanın değiştiği o kaotik PR’larda hayat kurtarıyor.
İşte tam da bu noktada devreye giriyor.
Bunu geçen ay İzmir’de küçük bir ürün ekibinde denedim diyebilirim — gerçi “denedim” kelimesi hafif kalır, neredeyse zorla geçirdik bu alışkanlığı. Aynı özellik için önce uzun uzun anlatılan serbest formatlı açıklamalar vardı; sonra What/Why/How’a geçtik (buna dikkat edin). Sorular ciddi biçimde azaldı. Bu ne anlama geliyor? Yeni katılan junior geliştiriciler bile konuyu çabuk kavradı çünkü metin akıyordu, okuyucu nereye bakacağını biliyordu.
Koddan çok bağlam taşıyın
Bunu yaşayan biri olarak söyleyeyim, Bazen tek başına diff yetmez. Bunu kabul edelim artık. “Session tokens were expiring mid-workflow” demek mesela çok daha faydalıdır çünkü sorun görünür olur; “Refresh tokens let us extend sessions without re-auth” dediğinizde de kararınız anlaşılır hale gelir. Pratikte bu yapı özellikle kurumsal projelerde bayağı iyi çalışıyor. Audit izi bırakıyorsunuz — altı ay sonra o PR’a bakan biri neden öyle karar aldığınızı anlayabiliyor.
Hmm, bunu nasıl anlatsamdı…
# İyi örnek iskelet
## What
Refactored the auth module to use JWT refresh tokens.
## Why
Session tokens were expiring mid-workflow (see #142).
Refresh tokens let us extend sessions without re-auth.
## How
- Added refreshToken() to AuthService
- Updated middleware to auto-refresh on 401
- Migration added for refresh_tokens table
- Tests updated for long-running uploads
Peki yorum yaparken nasıl konuşmalı?
Bence en temiz yöntem davranışı tarif etmek (buna dikkat edin). “This will panic on nil input” ile “You should add a nil check here” arasında ciddi ton farkı var; aynı şeyi söylüyorlar. Biri nesneye odaklanıyor, diğeri kişiye yükleniyor. Kurumsal tarafta ikinci yaklaşım hemen ters tepebiliyor — özellikle birbirini daha az tanıyan ekiplerde. RAG Neden Gerekli? LLM’lerin Kör Noktası yazımızda bu konuya da değinmiştik.
Açık konuşayım, ben kendi pull request’lerimde artık neredeyse hiç “you should” kullanmıyorum. Ha, bu arada bu sadece nezaket meselesi değil; aynı zamanda yanlış anlaşılmayı da azaltıyor. Nitpick seviyesinde önerilerde bile kısa kalıp yeterli oluyor: Daha fazla bilgi için Kuka’nın Sessiz Uyarısı: AI Avrupa’yı Neden Geride Bırakıyor? yazımıza bakabilirsiniz. Razor 1911: 40 Yıllık Dijital İsyan ve Demo Efsanesi yazımızda da bu konuya değinmiştik. YouTube TV’de 90 Saniyelik Reklam Şoku: İşler Karıştı yazımızda da bu konuya değinmiştik.
- Nit:
userCountreads better thancnt - Suggestion: Consider extracting this into a helper — it’s used in 3 places
- Blocking: This will panic on nil input — we need a guard here
Dikkat edin, burada cümlelerin odağı hep kodda kalıyor. Bu ufak kayma bile review kültürünü ciddi biçimde yumuşatıyor. Gerçi her takımda aynı etkiyi beklemek hayalcilik olur… bazı yerlerde insanlar hâlâ her şeyi kişisel algılıyor. Maalesef.
Kötü commit mesajından iyi commit mesajına geçiş
Son yıllarda en çok sevindiğim alışkanlıklardan biri Conventional Commits’e geçmek oldu. Tembel görünen birkaç kelime yerine biraz anlam koyunca geçmişe dönük tarama da kolaylaşıyor. Mesela fixed bug yerine fix(auth): prevent session expiry during active requests yazdığınızda herkes anında konuya giriyor. Neden önemli bu? Bu kadar basit yani.
| Zayıf mesaj | Kuvvetli mesaj | Etkisi |
|---|---|---|
| fixed bug | fix(auth): prevent session expiry during active requests | Tartışmayı azaltır ve tarihsel iz bırakır |
Manzara şöyle: özellik geliştikçe commit geçmişiniz küçük romanlara dönüşmesin… ama boş da olmasın. Ben kendi repolarımda bazen tam bu dengeyi kaçırdığımı fark ediyorum (kendi tecrübem). Yani evet, detay önemli; fakat günlük kullanım için iki satırlık netlik çoğu zaman fazlasıyla yeterli.
Küçük ekip ile enterprise ortamında aynı şey işlemiyor olabilir
Küçük startup tarafında amaç hızdır. PR description kısa olur ama eksik olmaz. Üç kişiyseniz fazla ritüele boğulmak anlamsız gelir zaten — herkes zaten ne döndüğünü biliyor, o bağlam kafanızda var. Ancak otuz-kırk kişilik mühendislik organizasyonunda durum değişir; orada bağlam kaybolduğu anda işler uzar, insanlar Slack’te birbirini arar, konu sürünür.
Enterprise seviyede ben özellikle iki şeye dikkat edilmesini seviyorum: biri migration veya breaking change notları, diğeri de kullanıcı etkisi (ciddiyim). Nasıl söyleyeyim… özellik güzel olabilir ama prod’da gece alarm çaldırıyorsa kimse onu alkışlamaz. Burada iyi yazılmış bir PR açıklaması ileride yaşanacak kafa karışıklığını önlüyor — bunu defalarca gördüm.
Bir startup’taki arkadaşım Temmuz 2025’te Londra’dan bana ekran görüntüsü atmıştı. “Tek cümlelik güzel commit attım,” dedi. Vallahi güzeldi ama sonradan geri dönüp baktıklarında neden o kararı aldıkları belli değildi. O yüzden bence denge şart: düzlük + bağlam + azıcık karakter.
20+ yıl deneyimli Azure Solutions Architect. Microsoft sertifikalı bulut mimari ve DevOps danışmanı. Azure, yapay zekâ ve bulut teknolojileri üzerine Türkçe teknik içerikler üretiyor.
İlgili Yazılar
Bu içerik işinize yaradı mı?
Benzer içerikleri kaçırmamak için beni sosyal medyada takip edin.
