Geliştiricilerin Proje Hafızası: Git’te İyi Belgelenmiş Kodun Gücü

Yazılım geliştirme kariyerimin ilk iki yılında commit mesajlarım olabildiğince basitti:

feat: ödeme özelliği oluştur

fix: kırık bağlantılar

Bu mesajlar dürüsttü ve çalışıyordu. Ancak ürün geliştirme evrim geçirip MVP aşamasını geride bıraktığında, bu tarz basitlikler ciddi sorunlara yol açmaya başladı.

Ekip büyüdükçe ya da CEO’lar, yatırımcılar ve denetçiler altı ay önce yapılan bir değişikliğin nedenini sormaya başladığında, kırık bağlantılar cevabı artık geçerli bir gerekçe değil, bir yükümlülük haline geliyor. Eğer Slack’teki sohbetlerde ve Notion sayfalarında geçirdiğiniz süre kod yazmaktan çoksa, belgelemelerinizin yeniden gözden geçirilmesi gerekiyor. Zira Git, neredeyse her projenin belgesi olarak hizmet ediyor.

Küçük Projeler İçin Geçerli, Büyük Projeler İçin Geçersiz

İç araçlar, prototipler ya da yalnızca iki kişinin dokunduğu veri akışları için fix: kırık bağlantılar gibi basit commit’ler yeterli olabilir. Her projenin FAANG düzeyinde disiplinli commit’lere ihtiyacı yoktur. Burada söz konusu olan, mikro yönetilen ekipler, büyük organizasyonlar ve çalışmalarını belgelemeleri gereken danışmanlardır. Eğer projeniz paydaşlar tarafından izleniyor ve uzun vadeli bakım gerektiriyorsa, commit disiplinine sıkı sıkıya bağlı kalın.

Git, Ürün Belgelerinizin Merkezinde Olmalı

Koddaki teknik tercihler ya da uygulama detaylarını harici araçlarda belgelediğinizde, süreç verimsiz hale geliyor. Tabii ki, büyük mimari kararlar ve iş stratejileri ayrı belgelerde ya da çalışma kitaplarında yer almalıdır. Ancak Git, kodla senkronize kalan tek belge kaynağıdır.

Günümüzde makineler — yapay zeka ajanları, otomatik değişim kaydı okuyucuları ve teknik denetçiler — commit geçmişinizi tarıyor. Projenizin mantığını anlamak için yalnızca Git’e bakacaklar. Commit’lerinizi onlar için optimize edin.

1. Commit Kapsamını Uygulayın

Genel ifadelerle yapılan commit’ler yeterli gibi görünse de, git log --grep gibi komutlarla geçmişi filtrelemek istediğinizde işler karmaşıklaşır. Conventional Commits gibi bir yapıyı benimseyerek, commit’lerinizin anında bağlam kazanmasını sağlayabilirsiniz.

Kötü: feat: Stripe desteği ekle

İyi: feat(payments): abonelik faturalandırması için Stripe entegrasyonu

Daha da İyi: fix(payments): Stripe webhook’unda eksik kalmış ödeme kimliği anahtarını ekle

Bu sayede, ödeme geçitini etkileyen tüm değişiklikleri anında görebilir ve geçmişi analiz edebilirsiniz.

2. Pull Request’leri Bir Öykü Olarak Düşünün

Bir Pull Request (PR), sadece kod yığını olmamalı; aynı zamanda bir hikaye anlatmalıdır. İşte önerilerim:

• PR’lerinizi 200-300 satırdan kısa tutun.
• Sadece teknik detayları değil, iş hedefini de açıklayın.
• Çalıştığınızı kanıtlamak için ekran görüntüleri, videolar veya terminal çıktıları ekleyin.
• PR başlığına ilgili ticket numarasını (#125 gibi) ekleyin. Bu, görev yönetimi ile kod arasındaki bağı güçlendirir.
• Henüz tamamlanmamış işler için draft modunu kullanın.
• PR atanmadan önce kendi incelemenizi yapın.
• Yorumlara cevap verin, düzeltme commit’leri gönderin, ardından disiplinli bir şekilde squash’leyin.

3. Commit Mesajının Gücünü Keşfedin

Çoğu geliştirici commit mesajını bir mesajlaşma uygulaması gibi kısa ve öz yazıyor. Bu, kaybedilen en büyük fırsatlardan biri. Büyük özellikler veya karmaşık yeniden düzenlemeler için commit gövdesini kullanın.

Örnek:

feat(payments): Ödeme Geçidi’ne PayPal stratejisi ekle
- ÖdemeServisi strateji desenine PayPal desteği eklendi.
- ÖdemeServisi test paketi, çoklu sağlayıcı kenar durumlarını kapsayacak şekilde genişletildi.
- PayPal API arızalarını yönetmek için Devre Kesici desen uygulandı.
Not: Avrupa pazarına açılmak için satış ekibinden gelen acil bir talepti.

Bu düzeydeki detaylar basit bir yazım hatası için fazla olabilir, ancak mimari değişiklikler ve büyük özellikler için zorunludur. Bu sayede, kullanılan bileşenler ve teknik tercihler anında belgelenmiş olur.

4. Dallanma Stratejisini Akıllıca Kullanın

Dallar, bir ekibin on farklı özelliği çakışmadan geliştirmesine olanak tanıyan izole ortamlardır. Temel kural: Asla `main` dalına doğrudan commit göndermeyin. main, şirketin para kazandığı ürün sürümünü temsil eder ve kutsaldır.

• Dalları niyetinize göre adlandırın. feat/payments-paypal ya da fix/auth-login-loop adı, kod açılmadan önce ekibe ne olduğunu anlatır.
• Bir dalı ticket numarasıyla adlandırdığınızda (feature/PROJECT-123), iş ve mühendislik arasındaki bağı kalıcı hale getirir.

Sonuç: Git, Projenizin Hafızasıdır

Git, sadece kodu kaydettiğiniz bir yer değildir; aynı zamanda projenizin belleğidir. Commit’lere ve PR’lere gösterdiğiniz disiplin sayesinde, Slack ve Notion’da kaybolan zamanı azaltabilirsiniz.

Net ve iyi yapılandırılmış bir Git geçmişi, yeni bir geliştiricinin, bir CEO’nun ya da bir yapay zeka aracının yazılımın arkasındaki mantığı anlamasını kolaylaştırır.

Ayrıca, GitHub commit’lerini teknik olmayan yöneticiler için raporlara dönüştüren Fabric adlı bir proje üzerinde çalışıyorum. Detayları öğrenmek için projenin GitHub sayfasını inceleyebilirsiniz.