Çerçeve Konvansiyonları Belgelerin Gerekliliğini Nasıl Azaltır

Konvansiyonlar Dokümantasyonun Yerini Aldığında Ne Anlama Gelir

Çerçeve konvansiyonları, bir framework'ün sessizce teşvik ettiği — veya doğrudan beklediği — “işlerin varsayılan yolu”dur. Her ekibin kendi klasör düzenini, adlandırma şemasını veya istek/yanıt akışını icat etmesi yerine framework ortak bir kalıp sağlar. Buna uyarsanız, diğer geliştiriciler uzun bir açıklamaya gerek kalmadan dosyaların nerede olduğunu ve nasıl davrandığını tahmin edebilir.

Ekipler neden dokümantasyon yazar

Çoğu dokümantasyon, insanların doküman yazmayı sevmesinden değil, birkaç tekrarlayan problemi çözmek için vardır:

• Onboarding: yeni geliştiricilere nereden başlayacaklarını ve projenin nasıl düzenlendiğini göstermek
• Tutarlılık: herkesin aynı problemi farklı şekillerde çözmesini önlemek
• Kararların kaydı: belirli bir yaklaşımın neden seçildiğini (genellikle takaslar sonrasında) belgelemek

Konvansiyonlar özellikle ilk iki sorunu iyi çözer. “X nerede durur” ve “Y'ye ne ad verilir” zaten framework tarafından belirlendiğinde, açıklanacak ve tartışılacak daha az şey kalır.

Konvansiyonlar dokümanları azaltır—ama yok etmez

“Konvansiyonlar dokümantasyonun yerini alır” demek, bir projenin dokümantasyonsuz olacağı anlamına gelmez. Anlamı şudur: temel rehberliğin büyük bir bölümü düzyazıdan öngörülebilir yapıya taşınır. Kontrollerin nerede olduğunu öğrenmek için bir wiki sayfası okumak yerine, framework'ün belirli bir yerde controller beklediğini çıkarırsınız (ve araçlar, jeneratörler ve örnekler bunu pekiştirir).

Sonuç: bariz olan hakkında daha az doküman, ve proje-özgü olanları (iş kuralları, sıra dışı mimari seçimler, kasıtlı istisnalar) belgelemeye daha fazla odaklanma.

Bu makaleden ne elde edeceksiniz

Bu yazı, daha net kod tabanları ve çok geniş bir dokümantasyon sitesi tutmadan daha hızlı onboarding isteyen geliştiriciler, teknoloji liderleri ve ürün odaklı ekipler içindir.

Framework konvansiyonlarının nasıl “örtük dokümantasyon” yarattığını, konvansiyonların genellikle neleri standartlaştırdığını, konvansiyonların nerede yetersiz kaldığını ve hangi konuların açıkça belgelenmeyi hak ettiğini öğreneceksiniz—böylece açıklık artarken doküman miktarı azalır.

Neden Konvansiyonlar İşe Yarar: Paylaşılan Varsayımlar Uzun Açıklamalardan Üstündür

“Konfigürasyon yerine konvansiyon” demek, bir framework'ün sizin için mantıklı seçimler yapması demektir—sizin o kabul edilmiş kuralları takip etmeniz koşuluyla. Sayfalarca kurulum talimatı yazıp okumak yerine ekipler herkesin tanıdığı ortak varsayımlara güvenir.

Basit bir benzetme

Bunu, herkesin sağdan araç sürdüğü, kırmızı ışıkta durduğu ve standart işaretleri takip ettiği bir ülkede araba kullanmaya benzetin.

Her kavşak için ayrıntılı bir el kitabı yazabilirsiniz (“Köşede kırmızı sekizgen görürseniz durun; ışık yeşilse geçin…”), ama buna gerek yok—çünkü konvansiyon zaten bilinir ve tutarlı şekilde uygulanır.

Framework konvansiyonları da aynı şekilde çalışır: “burada nasıl yapıyoruz”u öngörülebilir davranışa dönüştürür.

Varsayılanlar her adımı açıklama ihtiyacını kaldırır

Bir framework varsayılanlara sahip olduğunda, her küçük kararı belgelemeniz gerekmez. Framework (ve ekibiniz) şu tür kalıpları varsayabilir:

• dosyaların nerede olduğu (controllerlar bir klasörde, şablonlar başka bir yerde)
• adlandırmanın nasıl olduğu (bir User modeli users verisine eşlenir)
• yaygın özelliklerin nasıl bağlandığı (routing, doğrulama, ortam ayarları)

Bu ortak taban, dokümantasyonu “X'i kurmanın her adımı burada”dan “framework varsayımlarını takip ediyoruz, belirtilen yerler dışında”ya küçültür. Ayrıca onboarding sırasında zihinsel yükü azaltır: yeni geliştiriciler doğru tahminde bulunma olasılığı daha yüksek olur, çünkü kod başka projelerde gördükleriyle eşleşir.

Takas: daha az esneklik, daha fazla tutarlılık

Konvansiyonların bedeli vardır. Dezavantajı, bazen sıra dışı klasör yapılarına, özel adlandırmaya veya çok kişiye özel iş akışlarına veda etmenizdir.

Avantajı ise tutarlılıktır: daha az tartışma, daha az sürpriz, sadece uzun zamandır olanların hatırladığı “aşiret bilgisi” kuralları yerine daha fazla netlik. Ekipler daha hızlı ilerler çünkü açıklamaya daha az, inşa etmeye daha fazla zaman harcar.

Konvansiyonlar yaygın paylaşıldığında en iyi şekilde çalışır

Bir konvansiyon, insanlar zaten onu biliyorsa veya bir kez öğrenip her yerde tekrar kullanabiliyorsa doküman tasarrufu sağlar.

Bu yüzden popüler framework'ler güçlüdür: konvansiyonlar yaygın olarak öğretilir, kullanılır ve birçok kod tabanında tekrar edilir. Projeniz bu ortak varsayımlara yakın durduğunda, kodunuz varsayılan olarak anlaşılır hale gelir ve yazılı açıklamalara çok daha az ihtiyaç kalır.

Framework Konvansiyonlarının Genellikle Standartlaştırdığı 5 Şey

Framework konvansiyonları paylaşılan kısayollardır. Yeni bir ekip arkadaşının ilk gün sorduğu soruları standartlaştırırlar: “Bu nereye gider?” ve “Buna ne ad verilmeli?” Bu yanıtlar öngörülebilir olduğunda, bir dizi tutarlı varsayımla sayfalar dolusu dokümantasyonu değiştirebilirsiniz.

1) Klasör ve dosya yapısı

Çoğu framework tanınabilir bir proje yapısını teşvik eder: UI için bir yer, route'lar için bir yer, veri erişimi için bir yer, testler için bir yer. Bu tutarlılık önemlidir çünkü insanlar bir “sayfayı render eden parça” ile “veritabanıyla konuşan parça”yı bulmak için bir rehber okumak zorunda kalmazlar.

En iyi konvansiyonlar yaygın görevleri kas hafızası gibi hissettirir: yeni bir ekran eklediğinizde hangi klasöre koyacağınızı zaten bilirsiniz.

2) Adlandırma konvansiyonları

Adlandırma kuralları, “Controllerlarımız X'te ve Y'ye bağlı olmalı” gibi açıklamaları azaltır. İsimler rollerini ima eder.

Yaygın örnekler:

• hangi şeyi render ettiğini temel alan sayfa/bileşen adları (tahmin edilebilir büyük-küçük harf kullanımıyla)
• testlerin kapsadığı birime uygun adlandırılması
• dosyaların ihracatlarla eşleşecek şekilde adlandırılması (arama beklendiği gibi çalışsın diye)

3) Routing ve URL'ler

Birçok web framework dosyaları route'lara eşler (veya route'ların çıkarılmasını kolaylaştırır). Dosya adından URL'yi veya tersini tahmin edebiliyorsanız, her özellik için ayrı bir routing belgesine gerek yoktur.

Konvansiyon ayrıca dinamik route'lar, iç içe geçmiş route'lar ve 404 işlemleri hakkında beklentiler koyar, böylece “yeni bir endpoint nasıl eklenir?” sorusunun standart bir cevabı olur.

4) Veri erişim kalıpları

Konvansiyonlar genellikle “veri kodunun” nerede olduğunu tanımlar: modeller, repository'ler, servisler, migasyonlar, şema dosyaları. Uygulamanız küçük olsa bile, veri erişimi için kararlaştırılmış bir yerin olması UI kodu içinde rastgele dağılan veritabanı çağrılarını önler.

5) Yaygın scriptler ve komutlar

Çalıştırma, test etme, build, lint, format gibi standart komutlar belirsizliği ortadan kaldırır. Yeni bir geliştiricinin projeyi başlatmak için bir wiki sayfasına ihtiyacı olmamalı—npm test (veya eşdeğeri) mantıklı hareket olmalıdır.

Bu beş alan tutarlı olduğunda, kod tabanı çoğu “burada nasıl yapıyoruz?” sorusuna kendi başına cevap verir.

Konvansiyonlar Kod Tabanını Bir Haritaya Nasıl Dönüştürür

“Her şey nasıl çalışıyor” türündeki wiki, sistemi düzyazıyla açıklamaya çalışır. Başta faydalı olur, sonra klasörler taşındıkça, isimler değiştikçe ve yeni özellikler geldikçe güncelliğini kaybeder. Konvansiyonlar bu fikri tersine çevirir: uzun açıklama okumak yerine yapıyı "okursunuz".

Öngörülebilir yerler yönlenmeyi zahmetsiz kılar

Bir framework (ve ekibiniz) nerede ne olduğunu kabul ettiğinde, depo bir şehir ızgarası gibi gezilebilir hale gelir.

UI bileşenlerinin components/ içinde, sayfa seviyesindeki görünümlerin pages/ içinde ve API işleyicilerin api/ içinde olduğunu biliyorsanız, “X nerede?” diye sormayı bırakırsınız çünkü ilk tahmin genellikle doğrudur. Yanlış olduğunda bile aramanız daralır: herhangi bir yerde değil—beklenen birkaç yerden birindedir.

İsimler yol gösterir

Konvansiyonlar ayrıca dosya adlarının ve sembollerin anlam taşımasını sağlar. Yeni gelen, konum ve adımdan davranışı çıkarabilir:

• user.controller adlı bir dosya muhtemelen istek mantığını ele alır
• UserService sınıfı muhtemelen iş kurallarını barındırır
• migrations/ adlı bir klasör sıralı, bir defalık veritabanı değişikliklerini içerir

Bu çıkarım, “mimariyi bana anlat” sorusunu daha küçük, cevaplanabilir sorulara indirger (“Bu servis veritabanını doğrudan çağırabilir mi?”) ve bu sorular daha kolay belgelenir.

Şablonlar haritayı tutarlı kılar

Haritayı pekiştirmenin en hızlı yolu scaffolding'dir. Başlangıç şablonları ve jeneratörler, yeni özellikleri varsayılan olarak “doğru” biçimde oluşturur—klasörler, dosya adları, boilerplate ve genellikle testler.

Bu önemlidir çünkü konvansiyonlar yalnızca tutarlı uygulandıklarında yardımcı olur. Bir şablon koruyucu bir bariyer gibidir: her yeni route, bileşen veya modülün beklenen yapıya doğru itilmesini sağlar, böylece kod tabanı daha fazla wiki sayfası eklemeden okunaklı kalır.

İç şablonlarınız varsa, bunlara kısa bir onboarding sayfasından bağlanın (örneğin, /docs/getting-started) ve klasör ağacının geri kalanını bırakın.

“Örtük Dokümantasyon”un Gerçek Dünya Örnekleri

Framework konvansiyonları çoğu zaman sessiz, yerleşik talimatlar gibi davranır. “Dosyalar nereye gider” veya “bunu nasıl bağlarız” gibi bir sayfa yazmak yerine, framework zaten kararı vermiştir—ve ekip yapıyı okumayı öğrenir.

Ruby on Rails: “Buraya koy, çalışır”

Rails "konfigürasyon yerine konvansiyon" için ünlüdür. Basit bir örnek: OrdersController adında bir controller oluşturursanız, Rails app/views/orders/ içinde eşleşen bir view klasörü olduğunu varsayar.

Bu tek konvansiyon, aksi halde şu konuları açıklayacak bir doküman kümesini gereksiz kılar:

• HTML şablonlarının nerede olması gerektiği
• bir URL'nin doğru controller action'ı nasıl bulduğu
• controller'ın uygun şablonu nasıl seçtiği

Sonuç: yeni ekip üyeleri klasör desenini takip ederek bir sayfa ekleyebilir, “bu dosya nereye gider?” diye sormaya gerek kalmaz.

Django: yaygın işler için öngörülebilir yapı

Django, tutarlı bir “app” yapısını teşvik eder. Bir Django uygulaması gördüğünüzde models.py'de veri şekillerini, views.py'de istek işleyicileri ve templates/ içinde HTML dosyalarını bulacağınızı beklersiniz.

Projenizin anatomisini uzun uzun anlatabilirdiniz, ama Django'nun varsayımları zaten bunu öğretir. Bir ekip üyesi bir sayfanın görünümünü değiştirmek istediğinde templates/ dizinine bakacağını bilir; veriyi ayarlamak istediğinde models.py'de başlar.

Sonuç: daha hızlı düzeltmeler, daha az arama, “hangi dosya bunu kontrol ediyor?” mesajlarının azalması.

Next.js: bir routing el kitabına ihtiyaç duymadan routing

Next.js, routing'i klasör yapınızın doğrudan bir yansıması yaparak dokümantasyonu azaltır. app/about/page.tsx (veya eski düzenlerde pages/about.tsx) dosyası oluşturduğunuzda otomatik olarak bir /about sayfası elde edersiniz.

Bu, şu belgilerin gereksiz olmasını sağlar:

• route'ları nasıl kaydedeceğiniz
• route'ları nasıl tutarlı adlandıracağınız
• navigation'ı bozmadan yeni bir sayfa nasıl eklenir

Sonuç: onboarding daha basittir—insanlar dizinlere bakarak sitenin şeklini keşfedebilir.

Farklı ekosistemlerde aynı fikir

Rails, Django ve Next.js farklı görünür, ama prensip aynıdır: paylaşılan varsayımlar proje yapısını talimatlara dönüştürür. Herkes aynı konvansiyonlara güvendiğinde, kod tabanı çoğu “burada bunu nasıl yapıyoruz?” sorusunu kendi başına cevaplar—ekstra belgeye gerek kalmaz.

Konvansiyonlar Bozulduğunda (ve Karışıklığın Tekrar Döndüğünde)

Konvansiyonlar çalıştığında “görünmez” hissedilir. Dosyaların nerede olduğunu, şeylerin nasıl adlandırıldığını ve bir isteğin uygulamada nasıl aktığını tahmin edebilirsiniz. Karışıklık, bir kod tabanı bu ortak varsayımlardan uzaklaştığında geri döner.

Konvansiyonların aşındığını gösteren işaretler

Erken ortaya çıkan birkaç desen vardır:

• framework'ün olağan yapısıyla eşleşmeyen çok sayıda özel klasör (örneğin, her özellik için yeni üst seviye dizinler ve net kural yok)
• tutarsız adlandırma: bir yerde UserService, başka yerde UsersManager, başka bir yerde user_service
• ekrandan ekrana veya endpoint'ten endpoint'e değişen ad-hoc kalıplar (“burada farklı ele aldık çünkü…”) ve stabil bir kuralın olmaması

Bunların hiçbiri otomatik olarak yanlış değildir—ama yeni bir ekip üyesinin artık framework'ün “haritasına” güvenemeyeceği anlamına gelir.

“Bir istisna” nasıl çoğalır

Çoğu konvansiyon bozulması makul bir yerel optimizasyonla başlar: “Bu özellik özel, o yüzden buraya koyacağız” veya “Bu adlandırma daha iyi okunuyor”. Sorun şu: istisnalar bulaşıcıdır. İlk istisna çıktığında, bir sonraki geliştirici bunu emsal olarak kullanır:

• ikinci özellik özel klasörü kopyalar çünkü zaten orada
• üçüncü özellik biraz farklı uyarlama yapar çünkü ikinci tam uymaz
• kısa sürede aynı şey için üç “kabul edilebilir” yol olur

O anda, konvansiyon konvansiyon olmaktan çıkar—aşiret bilgisinin bir parçası haline gelir.

Gerçek maliyet: zaman, hatalar ve toplantılar

Konvansiyonlar bulanıklaştığında, onboarding yavaşlar çünkü insanlar nerede arayacaklarını tahmin edemez. Günlük görevler daha uzun sürer (“Bu klasörlerden hangisi gerçek olan?”), ve hatalar artar (yanlış modülü bağlama, yanlış adlandırma, mantığın kopyalanması). Ekipler bunu daha fazla senkronizasyon, uzun PR açıklamaları ve hızla bayatlaşan “kısa dokümanlar” ile telafi eder.

Netlik için basit bir kural

Açık bir nedeniniz olduğunda özelleştirin—ve yazılı bir not bırakın.

O not hafif olabilir: alışılmadık yapının yakınında kısa bir yorum veya ilgili klasörde küçük bir README.md. Bu, gelecekteki çalışmalarda standardın ne olması gerektiğini belirtir.

Hangi Konuları Hâlâ Belgelemeniz Gerekir: İstisnalar

Framework konvansiyonları sayfalar dolusu açıklamayı ortadan kaldırabilir, ama sorumluluğu ortadan kaldırmaz. Hâlâ belgelenmesi gereken kısımlar, projenizin kasıtlı olarak framework varsayımlarından farklı davrandığı yerlerdir.

Kararları belgeleyin, temelleri değil

Standart framework davranışını yeniden açıklamayı atlayın. Bunun yerine insanların günlük işlerini etkileyen kararları yakalayın:

• ne seçtiniz (ve neyi seçmediniz)
• ne değişti (ve ne zaman)
• neden değişti (takaslar, kısıtlamalar, olay-tabanlı düzeltmeler)

Örnek: “Sahiplik takımlarına göre eşleştirildiği ve takım-katmanlı bağımlılığı azalttığı için /src/features altında feature klasörleri kullanıyoruz.” Bu tek cümle haftalar süren sürüklenmeyi engeller.

Kodun yakınında kısa “İstisna Notları” bırakın

Bir istisna yerel olarak önemliyse, notu oraya koyun. Bir klasör içindeki küçük README.md veya bir dosyanın başındaki kısa bir yorum merkezi bir wiki sayfasından çok daha etkilidir.

İyi adaylar:

• olağan proje yapısını kasıtlı olarak bozan bir dizin
• alışılmadık bir sırayla başlatılması gereken bir modül
• kısıtlama bilinmezse “yanlış” görünen bir adlandırma kuralı

Notları kısa ve uygulanabilir tutun: ne farklı, neden farklı ve bir sonraki adım ne olmalı.

Küçük bir “Proje Kuralları” sayfası oluşturun

Bir hafif sayfa (genellikle /docs/project-rules.md veya root README) sadece ilk haftada insanları tökezletecek 5–10 ana seçimi listelesin:

• framework varsayımlarından farklı olan adlandırma kuralları
• beklenen proje yapısı (sadece farklılık olan yerlerde)
• yeni bir özellik/endpoint eklemek için “altın yolunuz”

Bu tam bir el kitabı değil—sadece paylaşılan bir dizi koruyucu çit.

Hızlı başlatma: nasıl çalıştırılır ve test edilir

Konvansiyonlar olsa bile insanlar projeyi çalıştıramadığında onboarding takılır. Kısa bir “Nasıl çalıştırılır/test edilir” bölümü ekleyin ve gerçek kurulumunuzu oraya yazın.

Eğer konvansiyonel komut npm test ise ama projeniz npm run test:unit gerektiriyorsa bunu açıkça belgeleyin.

Dokümanları güncel tutmayı kod incelemelerine dahil edin

Dokümanlar, değişikliğin bir parçası olarak ele alındığında doğru kalır. Kod incelemelerinde sorun: “Bu yeni bir istisna mı getiriyor?” Eğer evet ise, aynı pull request içinde eşlik eden notu (yerel README, Project Rules veya root quickstart) zorunlu kılın.

Konvansiyonları Daha Fazla Doküman Yerine Otomasyonla Zorlamak

Konvansiyonlar kod tabanınızın “paylaşılan varsayımları”ysa, otomasyon onları gerçeğe dönüştürendir. Her geliştiriciden bir wiki sayfasını hatırlamasını istemek yerine kuralları yürütülebilir hale getirin—böylece proje kendini uygular.

Ekipleri tutarlı tutan otomatik kontroller

İyi bir kurulum sürüklenmeyi erken ve sessizce yakalar:

• Formatlama: kaydetmede otomatik format ve CI'da format (ör. Prettier, gofmt, black) sayesinde stil tartışmaları ortadan kalkar.
• Lint kuralları: adlandırma konvansiyonlarını ve yaygın hataları engeller (ör. React hooks kuralları, kullanılmayan importlar, “varsayılan export yok” gibi kararlar).
• Test isimlendirme ve yapı kuralları: *.spec.ts, describe/it sözdizimi veya gerekli assertionlar gibi kalıpları zorunlu kılar.
• Klasör sınırları: hedef mimariyi ihlal eden importları engeller (ör. “feature'lar başka feature'dan import edemez” veya “UI sunucu kodunu import edemez”). ESLint kuralları, TypeScript path kısıtlamaları veya özel script'ler bunu sağlar.

Bu kontroller “lütfen hatırlayın” türü paragrafların yerini, kodun ya kurallara uyduğu ya da uymadığı basit sonucuyla değiştirir.

Hızlı başarısızlık: birleştirmeden önce sorunları yakalamak

Otomasyonun gücü şudur:

• problemler yerel geliştirme sırasında veya pull request'te bulunur, haftalar sonra değil
• gözden geçirenler stili denetlemek yerine ürün mantığına odaklanır
• yeni işe başlayanlar kuralları açık, tutarlı hatalar ve düzeltmeler görerek öğrenir

Kuralları minimal ve framework ile uyumlu tutun

En iyi kural setleri küçük ve sıkıcıdır. Framework'ün varsayılanlarıyla başlayın, sonra yalnızca netliği koruyanları ekleyin (adlandırma, yapı ve sınırlar). Her ek kural insanların anlaması gereken bir başka şeydir; yeni kontrolleri bir kod parçası gibi değerlendirin: tekrar eden bir problemi çözdüğünde ekleyin, yardımcı olmaktan çıktığında silin.

İnsanlar İçin Yazılmış Testler: Canlı Dokümantasyon

Bir kod tabanı framework konvansiyonlarını takip ettiğinde, testler yalnızca “çalıştığını kanıtlamak”tan daha fazlasını yapabilir. Testler, uygulanmanın yanında sistemin ne yapması gerektiğini açık dille anlatabilir.

Hikaye gibi okunacak testler yazın

Kullanışlı bir kural: bir test bir uçtan uca davranışı anlatmalı. Birisi test adını tarayıp sistemin verdiği sözü anlayabiliyorsa, ayrı bir dokümana olan ihtiyacı azaltmışsınız demektir.

İyi testler basit bir ritmi takip eder:

• Arrange: gerçekçi bir başlangıç noktası hazırla
• Act: tek bir eylem gerçekleştir
• Assert: önemli sonucu kontrol et

Daha da iyi isimlendirme kullanıcı niyetini yansıtır:

• signing_in_with_valid_credentials_redirects_to_dashboard
• checkout_fails_when_shipping_address_is_missing

Bu isimler, başarısız testlerin konuşmayı zorunlu kıldığı “unutulmayacak” bir dokümantasyondur.

Kullanıcı akışları için kabul testleri kullanın

Kabul (veya feature) testleri, ürünün bir kullanıcının perspektifinden nasıl davrandığını belgelemekte çok etkilidir.

Örnek davranışlar:

• kullanıcı kaydolur, e-postayı onaylar ve karşılama sayfasına yönlendirilir
• bir admin indirim kodu oluşturur ve bu ödeme sırasında uygulanır

Bu testler “X yaptığımda ne olur?” sorusunu yanıtlar—genellikle yeni bir ekip üyesinin ilk ihtiyaçlarından biri.

Birim testleri kenar durumlar ve kurallar için kullanın

Birim testleri, belgelenmesi gereken “küçük ama önemli” kurallar için idealdir:

• yuvarlama davranışı
• doğrulama kuralları
• izin kontrolleri
• zor köşe durumlar (zaman dilimleri, limitler, boş durumlar)

Framework konvansiyonlarından açıkça çıkmayan kurallar için özellikle değerlidirler.

Fixture'ları küçük ve anlamlı tutun

Örnek veriler de yaşayan dokümantasyon olabilir. Küçük, iyi adlandırılmış bir fixture (ör. user_with_expired_subscription) bir wiki paragrafından daha hızlı alana öğretir.

Anahtar nokta: ölçülü olmak. Fixture'ları minimal, okunabilir ve tek bir fikre bağlı tutun; böylece güvenilir örnekler olarak kalırlar, bakım gerektiren ikinci bir sisteme dönüşmezler.

Başlangıç Şablonları: Konvansiyonları Yaymanın En Hızlı Yolu

Başlangıç şablonları (ve bunları oluşturan jeneratörler), “burada nasıl yapıyoruz”u insanların gerçekten takip edeceği bir şeye dönüştürmenin en hızlı yoludur. Her ekip üyesine doğru klasörleri, scriptleri ve araçları hatırlatmaktansa, bu kararları doğru başlayacak bir repoya gömün.

Şablonlar, jeneratörler ve başlangıç kitleri: farklı hızlar, aynı hedef

• Şablonlar kopyalanabilir bir temel verir (örn. “yeni servis”, “yeni frontend uygulama”).
• Jeneratörler (CLI araçları) birkaç soru sorup tutarlı dosyaları, adlandırmayı ve bağlantıları oluşturabilir.
• Başlangıç kitleri genellikle sadece kod yapısını değil, CI, linting, test ve dağıtım varsayımlarını da içerir.

Üçü de “dokümantasyon borcunu” azaltır çünkü konvansiyonlar başlangıç noktasına kodlanmıştır; drift eden bir wiki'ye değil.

Uygulamada, Koder.ai gibi araçlar yardımcı olabilir: yeni bir React uygulaması, Go backend, PostgreSQL şeması veya Flutter istemcisi oluşturduğunuzda, varsayılan çıktıyı ekip standartlarınıza uygun hale getirerek takımları tek bir “altın yol”da tutabilirsiniz.

Kurulumu standartlaştırın ki “her depo farklı olmasın”

Onboarding sırasında ortaya çıkan karışıklığın çoğu iş mantığı ile değil, şeylerin nerede olduğu ve nasıl çalıştırılacağı ile ilgilidir. İyi bir şablon yaygın görevleri tüm repolarda aynı yapar: aynı scriptler, aynı klasör adları, aynı kontrol komutları, aynı PR beklentileri.

Yapmanız gerekenler:

• öngörülebilir klasörler (örn. /src, /test, /docs yalnızca istisnalar için)
• tek bir komutla kurulum ve çalıştırma (örn. install + dev)
• test, lint ve format scriptleri
• PR başına çalışan varsayılan CI pipeline

Hafif bir “yeni proje” kontrol listesi

Ekiplerin atlamayacağı kadar küçük tutun:

1. Klasör yapısı ve adlandırma kuralları
2. Tek komutla kurulum (örn. install + dev)
3. test, lint ve format scriptleri
4. Her PR'da çalışan CI
5. Temel README: amaç, önkoşullar ve insanların ihtiyaç duyduğu 3–5 komut

Fosilleşmeyin: şablonun kendisi sorun olabilir

En büyük risk, “geçen yıl işe yaradı” diye eski bir şablonu kopyalamaktır. Eski bağımlılıklar, kalıntı scriptler veya terk edilmiş kalıplar bir şablon içinde hızla yayılır.

Şablonları bir ürün gibi düşünün: versiyonlayın, planlı olarak gözden geçirin ve konvansiyonlar değiştiğinde güncelleyin. (Platformunuz snapshot ve geri alma destekliyorsa—Koder.ai gibi—starter'larda güvenli yineleme için bunları kullanın.)

Dokümanları Azaltırken Netliği Kaybetmeme için Pratik Kontrol Listesi

Dokümantasyonu azaltmak insanların tahmin etmesine bırakmak demek değildir. Mutlu yolu o kadar tutarlı yapın ki çoğu soru kendi kendine cevaplansın ve sadece gerçekten olağan dışı parçalar yazılı olsun.

1) Kısa bir öz-değerlendirme yapın (gerçek sürtüşmeyi bulun)

Slack, PR yorumları, standup'lar veya onboarding oturumlarında insanların tekrar tekrar sorduğu yerleri arayın. Bazı yönlendirici sorular:

• “Bu dosya nerede durmalı?”
• “Buna ne ad veriyoruz?”
• “Yeni bir sayfa/job/endpoint nasıl eklenir?”
• “Neden bu modülde farklı çalışıyor?”

Aynı soruyu iki kere duyuyorsanız, muhtemelen daha fazla düzyazıya değil, bir konvansiyona ihtiyacınız var.

2) Seçin: framework varsayımlarını benimseyin veya kasıtlı sapmayı belgeleyin

Her tekrar eden soru için şu kararlardan birini verin:

• Framework ile savaşıyoruz: framework'ün varsayılanlarına dönün (routing, klasör düzeni, adlandırma, hata işleme). Varsayılanlar ekosistem tarafından zaten “belgelenmiştir”.
• Farklı olmamız için iyi bir neden var: sapmayı koruyun, ama bunun açık ve kolay bulunur olmasını sağlayın.

Kullanışlı bir kural: bir sapma gerçek zaman kazandırmıyor veya gerçek riski azaltmıyorsa, muhtemelen devam eden karışıklığa değmez.

3) Tek bir küçük “Konvansiyonlar ve İstisnalar” sayfası oluşturun

Kısa bir sayfa (örn. /docs/conventions) şunları listelemeli:

• herkesin varsayması gereken 5–10 konvansiyon
• küçük bir istisna kümesi (neden ve bir örnek ile)

İlk hafta içinde ihtiyaç duyulabilecek kadar kısa tutun. Büyürse, genellikle kod tabanını basitleştirmeniz gerektiğinin işaretidir.

4) Rutin belirleyin: konvansiyonları üç ayda bir gözden geçirin

Uygulamalar evrilir. Hafif bir üç aylık gözden geçirme planlayın:

• hangi yeni kalıplar ortaya çıktı?
• hangi istisnalar “normal” hale geldi (ve konvansiyon olmalı)?
• hangi konvansiyonlar göz ardı ediliyor (ve neden)?

Özet

Mümkün olduğunca framework varsayılanlarını tercih edin ve sadece farklı olanları—açık, kısa ve tek bir yerde—belgeleyin.