Çerçeve konvansiyonları, uzun dokümantasyonlara ihtiyaç duymadan uygulamaların daha kolay anlaşılmasını sağlar. Hangi alanları kapsadıklarını, nerede yetersiz kaldıklarını ve yalnızca istisnaları nasıl belgelendireceğinizi öğrenin.
Ç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.
Çoğu dokümantasyon, insanların doküman yazmayı sevmesinden değil, birkaç tekrarlayan problemi çözmek için vardır:
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ü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 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.
“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.
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.
Bir framework varsayılanlara sahip olduğunda, her küçük kararı belgelemeniz gerekmez. Framework (ve ekibiniz) şu tür kalıpları varsayabilir:
User modeli users verisine eşlenir)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.
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.
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ı 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.
Ç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.
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:
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.
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.
Ç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.
“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".
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.
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ırUserService sınıfı muhtemelen iş kurallarını barındırırmigrations/ adlı bir klasör sıralı, bir defalık veritabanı değişikliklerini içerirBu çı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.
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.
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.
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:
Sonuç: yeni ekip üyeleri klasör desenini takip ederek bir sayfa ekleyebilir, “bu dosya nereye gider?” diye sormaya gerek kalmaz.
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, 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:
Sonuç: onboarding daha basittir—insanlar dizinlere bakarak sitenin şeklini keşfedebilir.
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 ç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.
Erken ortaya çıkan birkaç desen vardır:
UserService, başka yerde UsersManager, başka bir yerde user_serviceBunları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.
Ç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:
O anda, konvansiyon konvansiyon olmaktan çıkar—aşiret bilgisinin bir parçası haline gelir.
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.
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.
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.
Standart framework davranışını yeniden açıklamayı atlayın. Bunun yerine insanların günlük işlerini etkileyen kararları yakalayın:
Ö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.
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:
Notları kısa ve uygulanabilir tutun: ne farklı, neden farklı ve bir sonraki adım ne olmalı.
Bir hafif sayfa (genellikle /docs/project-rules.md veya root README) sadece ilk haftada insanları tökezletecek 5–10 ana seçimi listelesin:
Bu tam bir el kitabı değil—sadece paylaşılan bir dizi koruyucu çit.
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, 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 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.
İyi bir kurulum sürüklenmeyi erken ve sessizce yakalar:
*.spec.ts, describe/it sözdizimi veya gerekli assertionlar gibi kalıpları zorunlu kı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.
Otomasyonun gücü şudur:
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.
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.
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:
Daha da iyi isimlendirme kullanıcı niyetini yansıtır:
signing_in_with_valid_credentials_redirects_to_dashboardcheckout_fails_when_shipping_address_is_missingBu isimler, başarısız testlerin konuşmayı zorunlu kıldığı “unutulmayacak” bir dokümantasyondur.
Kabul (veya feature) testleri, ürünün bir kullanıcının perspektifinden nasıl davrandığını belgelemekte çok etkilidir.
Örnek davranışlar:
Bu testler “X yaptığımda ne olur?” sorusunu yanıtlar—genellikle yeni bir ekip üyesinin ilk ihtiyaçlarından biri.
Birim testleri, belgelenmesi gereken “küçük ama önemli” kurallar için idealdir:
Framework konvansiyonlarından açıkça çıkmayan kurallar için özellikle değerlidirler.
Ö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ı (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.
Üçü 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.
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:
/src, /test, /docs yalnızca istisnalar için)install + dev)test, lint ve format scriptleriEkiplerin atlamayacağı kadar küçük tutun:
install + dev)test, lint ve format scriptleriEn 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ü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.
Slack, PR yorumları, standup'lar veya onboarding oturumlarında insanların tekrar tekrar sorduğu yerleri arayın. Bazı yönlendirici sorular:
Aynı soruyu iki kere duyuyorsanız, muhtemelen daha fazla düzyazıya değil, bir konvansiyona ihtiyacınız var.
Her tekrar eden soru için şu kararlardan birini verin:
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.
Kısa bir sayfa (örn. /docs/conventions) şunları listelemeli:
İlk hafta içinde ihtiyaç duyulabilecek kadar kısa tutun. Büyürse, genellikle kod tabanını basitleştirmeniz gerektiğinin işaretidir.
Uygulamalar evrilir. Hafif bir üç aylık gözden geçirme planlayın:
Mümkün olduğunca framework varsayılanlarını tercih edin ve sadece farklı olanları—açık, kısa ve tek bir yerde—belgeleyin.
Çerçeve konvansiyonları, bir framework'ün takip etmenizi beklediği varsayılan kalıplardır — klasör yapısı, adlandırma, yönlendirme, veri erişimi ve yaygın komutlar gibi. Bu konvansiyonlara uyduğunuzda, diğer geliştiriciler proje-özgü dokümanları okumadan dosyaların nerede olduğunu ve nasıl çalıştığını çıkarabilirler.
Çünkü kod tabanı değiştikçe yazılı metni güncel tutmak zordur. Dokümanlar esas olarak şunları sağlamak için vardır:
Konvansiyonlar ilk ikisini kapatarak yapıyı öngörülebilir hale getirir.
Hayır. Konvansiyonlar, dosyaların nerede olduğu veya yönlendirmelerin nasıl bağlandığı gibi bariz konulardaki dokümanları azaltır; ancak hala proje-özgü olanları belgelemeniz gerekir: iş kuralları, kasıtlı sapmalar ve önemli kararlar. Yani “daha az doküman, daha yüksek değerli doküman” düşünün.
Günlük "ilk gün" sorularını standartlaştırırlar:
Kod belirli kalıpları takip ettiğinde, dizin ağacı ve dosya adları işaretler gibi davranır. Yeni gelen biri, "şablonlar templates/ dizininde" veya "migasyonlar migrations/ içinde" gibi beklentilerle gezinebilir; uzun ve güncelliğini yitiren bir mimari sayfası okumaya gerek kalmaz.
Konvansiyonları varsayılanlara kodlayarak (şablonlar, jeneratörler) insanlar belleğe güvenmek zorunda kalmaz. İyi scaffoldlar şunları üretir:
Bu, sürüklenmeyi engeller ve projenin şeklini tutarlı kılar.
Geliştiricilerin dosyaların nerede olduğunu veya nasıl adlandırıldığını tahmin edememesiyle belli olur. Yaygın belirtiler:
UserService vs UsersManager vs user_service)Bunlar belirlendiğinde ekip Slack açıklamaları, uzun PR'lar ve bayat “hızlı dokümanlar” ile telafi eder.
Sadece açık bir fayda olduğunda özelleştirin ve o zaman hafif bir not bırakın:
README.md/docs/decisions benzeri bir yerde bir girişNe değişti, neden değişti ve gelecekte standart yaklaşım ne olmalı—bunları yakalayın.
Başlangıç için küçük ve pratik bir temel yazın:
Sade tutun ve bir değişiklik yeni bir istisna getiriyorsa PR sırasında eşlik eden notu zorunlu kılın.
Konvansiyonları yürütülebilir hale getirmek için otomasyon kullanın:
Kontroller yerelde veya PR'larda başarısız olduğunda geliştiriciler kuralları hemen öğrenir; gözden geçirenler stil denetiminden daha çok ürün mantığına odaklanır.
Bunlar öngörülebilir olduğunda depo kendini açıklayıcı olur.