फ़्रेमवर्क मानक कोडबेस को अनुमान्य बनाकर लंबे दस्तावेज़ों की ज़रूरत घटाते हैं। जानिए कौन-सी चीज़ें कन्वेंशंस कवर करती हैं, कहां वे असफल रहते हैं, और किन अपवादों को ही दस्तावेज़ करना चाहिए।
फ़्रेमवर्क कन्वेंशंस वे “डिफ़ॉल्ट तरीके” होते हैं जिन्हें एक फ़्रेमवर्क चुपचाप बढ़ावा देता है—या जिनकी वह सख्ती से उम्मीद करता है। हर टीम को अपना फ़ोल्डर लेआउट, नामकरण स्कीम, या अनुरोध/प्रतिक्रिया फ्लो इत्यादि आविष्कार करने की बजाय, फ़्रेमवर्क एक साझा पैटर्न देता है। यदि आप उसे फ़ॉलो करते हैं, तो दूसरे डेवलपर्स बिना लंबी व्याख्या के अनुमान लगा सकते हैं कि चीज़ें कहाँ रहती हैं और कैसे व्यवहार करेंगी।
ज़्यादातर दस्तावेज़ इसलिए नहीं लिखे जाते कि लोग लिखना पसंद करते हैं। वे कुछ आवर्ती समस्याओं को हल करने के लिए मौजूद होते हैं:
कन्वेंशंस विशेष रूप से पहले दो को बहुत अच्छे से हल करते हैं। जब “X कहाँ रखें” और “Y को क्या नाम दें” जैसी बातें पहले से फ़्रेमवर्क द्वारा तय हों, तो समझाने के लिए कम होता है और बहस भी कम होती है।
“कन्वेंशन दस्तावेज़ीकरण की जगह लेते हैं” का अर्थ यह नहीं है कि एक प्रोजेक्ट दस्तावेज़-मुक्त हो जाता है। इसका मतलब है कि बुनियादी मार्गदर्शन का एक बड़ा हिस्सा prose से अनुमान्य संरचना में चला जाता है। कंट्रोलर कहाँ होते हैं यह जानने के लिए विकि पेज पढ़ने के बजाय, आप यह निहित तौर पर समझ लेते हैं क्योंकि फ़्रेमवर्क अपेक्षा करता है कि कंट्रोलर किसी खास जगह पर हों (और टूल्स, जनरेटर और उदाहरण इसे मजबूत करते हैं)।
परिणाम: स्पष्ट बातों के बारे में कम दस्तावेज़, और अधिक ध्यान उस पर जो सचमुच प्रोजेक्ट-विशेष है: बिज़नेस नियम, असामान्य आर्किटेक्चर विकल्प, और जानबूझकर किए गए अपवाद।
यह लेख डेवलपर्स, टेक लीड्स, और प्रोडक्ट-मनाए टीमों के लिए है जो एक साफ़ कोडबेस और तेज़ ऑनबोर्डिंग चाहते हैं बिना एक विस्तृत दस्तावेज़ साइट बनाए।
आप जानेंगे कि फ़्रेमवर्क कन्वेंशन कैसे “निहित दस्तावेज़ीकरण” बनाते हैं, किस तरह की चीज़ों को कन्वेंशन सामान्यतः स्टैंडर्डाइज़ करते हैं, कहां कन्वेंशन मदद करना बंद कर देते हैं, और फिर भी किन चीज़ों को स्पष्ट रूप से दस्तावेज़ित करना चाहिए—ताकि स्पष्टता बढ़े भले ही दस्तावेज़ कम हों।
“Convention over configuration” का मतलब है कि एक फ़्रेमवर्क आपके लिए समझदार विकल्प चुनता है—जब तक आप उसके सहमत नियमों का पालन करते हैं। कई सेटअप निर्देशों के पन्ने लिखने (और पढ़ने) के बजाय, टीमें साझा डिफ़ॉल्ट्स पर निर्भर करती हैं जिन्हें हर कोई पहचानता है।
इसे उस देश की ड्राइविंग की तरह सोचें जहाँ हर कोई दाहिनी ओर ही गाड़ी चलाने, लाल बत्ती पर रुकने, और मानक संकेतों का पालन करने पर सहमत है।
आप लिख सकते थे कि हर चौराहे के लिए विस्तृत मैनुअल (“यदि आप लाल अष्टभुज देखें तो रुको; यदि लाइट हरी है तो जाओ…”), पर इसकी ज़रूरत नहीं है—क्योंकि कन्वेंशन पहले से जाना हुआ और लगातार लागू होता है।
फ़्रेमवर्क कन्वेंशन भी इसी तरह काम करते हैं: वे “यहाँ हम कैसे काम करते हैं” को अनुमान्य व्यवहार में बदल देते हैं।
जब फ़्रेमवर्क के पास डिफ़ॉल्ट होते हैं, तो आपको हर छोटे निर्णय को दस्तावेज़ करने की ज़रूरत नहीं पड़ती। फ़्रेमवर्क (और आपकी टीम) ऐसे पैटर्न मान सकती है जैसे:
User मॉडल का मैप users डेटा से)यह साझा बेसलाइन दस्तावेज़ को इस तरह छोटा कर देती है कि अब वह "X सेटअप करने के हर कदम" से बन कर "हम फ़्रेमवर्क डिफ़ॉल्ट का पालन करते हैं, जहाँ अलग है वहां बताया गया है" बन जाता है। यह ऑनबोर्डिंग के दौरान मानसिक लोड भी घटाता है: नए डेवलपर्स अक्सर सही अनुमान लगा लेते हैं, क्योंकि कोड ने उन्हें पहले से देखे पैटर्न से मेल खाता है।
कन्वेंशंस मुफ़्त नहीं हैं। नकारात्मक पक्ष यह है कि कभी-कभी आपको असामान्य फ़ोल्डर संरचनाओं, कस्टम नामकरण, या अत्यंत अनोखे वर्कफ़्लो की आज़ादी छोड़नी पड़ती है।
फायदा यह है कि सुसंगतता आती है: कम बहसें, कम आश्चर्य, और कम "जनजातीय ज्ञान" वाले नियम जो केवल पुराने लोगों को याद रहते हैं। टीमें तेज़ी से आगे बढ़ती हैं क्योंकि वे समझाने में कम और बनाने में ज़्यादा समय लगाती हैं।
एक कन्वेंशन तभी दस्तावेज़ बचाता है जब लोग उसे पहले से जानते हों—या एक बार सीख कर बार-बार उपयोग कर सकें।
यही कारण है कि लोकप्रिय फ़्रेमवर्क शक्तिशाली होते हैं: उनके कन्वेंशंस व्यापक रूप से पढ़ाए जाते हैं, व्यापक रूप से उपयोग किए जाते हैं, और कई कोडबेस में दोहराए जाते हैं। जब आपका प्रोजेक्ट उन साझा डिफ़ॉल्ट्स के करीब रहता है, तो आपका कोड स्वतः ही समझ में आने लगता है, कम लिखे गए स्पष्टीकरणों के साथ।
फ़्रेमवर्क कन्वेंशंस साझा शॉर्टकट होते हैं। वे उन सवालों को स्टैंडर्डाइज़ करते हैं जो हर नए साथी पहले दिन पूछता है: “यह कहाँ जाए?” और “इसे क्या नाम दें?” जब उन जवाबों का अनुमान लगाना संभव हो, आप कई पन्नों की डॉक्यूमेंटेशन को कुछ सुसंगत डिफ़ॉल्ट से बदल सकते हैं।
ज़्यादातर फ़्रेमवर्क एक मान्यता प्राप्त प्रोजेक्ट संरचना को बढ़ावा देते हैं: UI के लिए एक जगह, रूट्स के लिए एक जगह, डेटा एक्सेस के लिए एक जगह, और टेस्ट्स के लिए एक जगह। यह सुसंगतता इसलिए महत्वपूर्ण है क्योंकि लोगों को यह जानने के लिए किसी गाइड को पढ़ने की ज़रूरत नहीं पड़ती कि "पृष्ठ प्रस्तुत करने वाला भाग" और "डेटाबेस से बात करने वाला भाग" कहाँ है।
सबसे अच्छी कन्वेंशंस आम कामों को मांसपेशी स्मृति जैसा बना देती हैं: नया स्क्रीन जोड़ें, आपको पहले से पता होगा कि किस फ़ोल्डर में यह होगा।
नामकरण नियम यह समझाने की ज़रूरत घटाते हैं जैसे “हमारे कंट्रोलर्स X में हैं और Y में वायर किए जाने चाहिए।” इसके बजाय, नाम भूमिकाओं का संकेत देते हैं।
साधारण उदाहरण:
कई वेब फ़्रेमवर्क फ़ाइलों को रूट्स से मैप करते हैं (या रूट्स का अनुमान लगाना आसान बनाते हैं)। यदि आप फ़ाइल-नाम से URL का अनुमान लगा सकते हैं—या इसके विपरीत—तो हर फीचर के लिए अलग रूटिंग डॉक्यूमेंट की ज़रूरत नहीं रहती।
कन्वेंशन डायनामिक रूट्स, नेस्टेड रूट्स, और 404 हैंडलिंग के आस-पास की उम्मीदें भी सेट करती है, ताकि “हम एक नया एंडपॉइंट कैसे जोड़ते हैं?” का एक मानक उत्तर हो।
कन्वेंशंस अक्सर यह परिभाषित करते हैं कि “डेटा कोड” कहाँ रहता है: models, repositories, services, migrations, schema फ़ाइलें। भले ही आपका ऐप छोटा हो, डेटा एक्सेस के लिए एक सहमत स्थान होने से UI कोड में बिखरे हुए ad-hoc DB कॉल्स से बचाव होता है।
मानक कमांड्स (run, test, build, lint, format) अस्पष्टता दूर करते हैं। नया डेवलपर किसी विकि पेज को पढ़े बिना आसानी से प्रोजेक्ट को शुरू कर सके—npm test (या समकक्ष) स्पष्ट चाल होना चाहिए।
इन पाँच क्षेत्रों में सुसंगतता होने पर, कोडबेस खुद ही अधिकांश “यहाँ हम कैसे करते हैं?” सवालों के जवाब दे देता है।
"कैसे सब कुछ काम करता है" वाली विकि पूरी सिस्टम को prose में समझाने की कोशिश करती है। यह अक्सर उपयोगी शुरू होती है, फिर जैसे-जैसे फ़ोल्डर्स हिलते हैं, नाम बदलते हैं, और नई सुविधाएँ आती हैं, वह पुरानी पड़ जाती है। कन्वेंशंस इस विचार को उल्टा कर देते हैं: लंबे स्पष्टीकरण पढ़ने के बजाय, आप संरचना पढ़ते हैं।
जब एक फ़्रेमवर्क (और आपकी टीम) यह तय कर लेती है कि चीज़ें कहाँ रहती हैं, रिपॉज़िटरी एक शहर के ग्रिड जैसी नेविगेबल बन जाती है।
यदि आप जानते हैं कि UI components components/ में जाते हैं, पृष्ठ-स्तर दृश्य pages/ में होते हैं, और API हैंडलर्स api/ में रहते हैं, तो आप “X कहाँ है?” पूछना बंद कर देते हैं क्योंकि पहला अनुमान आम तौर पर सही होता है। भले ही वह सही न हो, आपकी खोज सीमित रहती है: यह कहीं भी नहीं—यह अनुमानित जगहों में से किसी एक में है।
कन्वेंशंस फ़ाइल-नामों और प्रतीकों को अर्थ से भर देते हैं। नया सहयोगी स्थान और नाम देखकर व्यवहार का अनुमान लगा सकता है:
user.controller नाम की फ़ाइल संभवतः अनुरोध लॉजिक संभालती हैUserService क्लास संभवतः बिज़नेस नियम रखती हैmigrations/ नाम का फ़ोल्डर संभवतः क्रमबद्ध, एक-बार-रन करने वाले डेटाबेस परिवर्तन रखता हैयह अनुमान “मुझे आर्किटेक्चर समझाओ” जैसे प्रश्नों को छोटे, उत्तरयोग्य सवालों में बदल देता है (“क्या यह सर्विस सीधे DB को कॉल कर सकती है?”), जिन्हें दस्तावेज़ित करना आसान होता है।
मानचित्र को मज़बूत करने का सबसे तेज़ तरीका scaffolding है। स्टार्टर टेम्पलेट्स और जनरेटर नई सुविधाओं को डिफ़ॉल्ट रूप से “सही” आकार में बनाते हैं—फ़ोल्डर्स, फ़ाइल-नाम, बायलरप्लेट वायरिंग, और अक्सर टेस्ट भी।
यह मायने रखता है क्योंकि कन्वेंशंस तभी मदद करती हैं जब वे सुसंगत रूप से लागू हों। एक टेम्पलेट गार्डरेल का काम करता है: यह हर नए रूट, कॉम्पोनेंट, या मॉड्यूल को अपेक्षित संरचना में धकेलता है, ताकि कोडबेस पठनीय बना रहे बिना और विकि पेज जोड़ने की ज़रूरत पड़े।
यदि आप आंतरिक scaffolds बनाए रखते हैं, तो उन्हें एक छोटे ऑनबोर्डिंग पृष्ठ (उदा., /docs/getting-started) से लिंक करें और फ़ोल्डर ट्री को बाकी काम करने दें।
फ़्रेमवर्क कन्वेंशंस अक्सर शांत, अंतर्निहित निर्देशों की तरह कार्य करते हैं। "कहाँ चीज़ें जाती हैं" या "इसे कैसे वायर करें" समझाने वाले पन्ने लिखने की बजाय, फ़्रेमवर्क पहले से ही निर्णय ले लेता है—और आपकी टीम संरचना पढ़ना सीख जाती है।
Rails "convention over configuration" के लिए प्रसिद्ध है। एक सरल उदाहरण: यदि आप OrdersController नाम का कंट्रोलर बनाते हैं, तो Rails मान लेता है कि एक मिलता-जुलता view फ़ोल्डर app/views/orders/ में है।
यह एक बड़ा हिस्सा दस्तावेज़ीकरण का स्थान ले सकता है जो अन्यथा यह बताता:
परिणाम: नया साथी फ़ोल्डर पैटर्न का पालन कर के एक पेज जोड़ सकता है बिना पूछे "यह फ़ाइल कहाँ जाए?"
Django एक सुसंगत “app” संरचना को प्रोत्साहित करता है। जब कोई Django ऐप देखता है, तो वे उम्मीद करते हैं कि models.py डेटा आकृतियों के लिए, views.py रिक्वेस्ट हैंडलिंग के लिए, और templates/ HTML के लिए मिलेंगे।
आप एक लंबा गाइड लिख सकते थे जो आपके प्रोजेक्ट की संरचना बताता है, पर Django के डिफ़ॉल्ट्स पहले से ही इसे सिखा देते हैं। जब किसी साथी को यह बदलना हो कि पृष्ठ कैसे दिखता है, वे templates/ में देखना शुरू करते हैं। जब उन्हें संग्रहित डेटा समायोजित करना हो, वे models.py में जाते हैं।
परिणाम: तेज़ फिक्स, कम खोज का समय, और कम “कौन सी फ़ाइल इसे कंट्रोल करती है?” संदेश।
Next.js दस्तावेज़ीकरण कम करता है क्योंकि रूटिंग सीधे आपकी फ़ोल्डर संरचना का प्रतिबिंब होती है। app/about/page.tsx (या पुराने सेटअप में pages/about.tsx) में फ़ाइल बनाएं, और आपको ऑटोमेटिकली /about पेज मिल जाता है।
इससे दस्तावेज़ की ज़रूरत घट जाती है जो बताती:
परिणाम: ऑनबोर्डिंग सरल है—लोग निर्देशिकाएँ देखकर साइट का आकार खोज लेते हैं।
Rails, Django, और Next.js अलग दिखते हैं, पर सिद्धांत समान है: साझा डिफ़ॉल्ट परियोजना संरचना को निर्देशों में बदल देते हैं। जब हर कोई एक ही कन्वेंशंस पर भरोसा करता है, तो कोडबेस स्वयं कई "हम यहाँ कैसे करते हैं?" सवालों के जवाब दे देता है—बिना अलग दस्तावेज़ बनाए रखने के।
फ़्रेमवर्क कन्वेंशंस तब “अदृश्य” लगते हैं जब वे काम कर रहे होते हैं। आप अनुमान लगा सकते हैं कि फ़ाइलें कहाँ रहती हैं, क्या नाम दिया जाता है, और रिक्वेस्ट ऐप में कैसे बहती है। भ्रम तब लौटता है जब कोडबेस उन साझा डिफ़ॉल्ट्स से दूर चला जाता है।
कुछ पैटर्न जल्दी दिखते हैं:
UserService, दूसरी जगह UsersManager, तीसरी जगह user_serviceइनमें से कोई भी स्वचालित रूप से गलत नहीं है—पर वे दर्शाते हैं कि नया साथी अब फ़्रेमवर्क के "मैप" पर भरोसा नहीं कर सकता।
ज़्यादातर कन्वेंशन ब्रेक्स एक स्थानीय अनुकूलन से शुरू होते हैं: "यह फीचर खास है, इसलिए हम इसे यहाँ रखें" या "यह नाम बेहतर पढ़ता है"। समस्या यह है कि अपवाद संक्रामक होते हैं। एक बार पहला अपवाद शिप हो गया, अगला डेवलपर उसे मिसाल मान लेता है:
उस बिंदु पर, कन्वेंशन अब कन्वेंशन नहीं रहती—यह जनजातीय ज्ञान बन जाती है।
जब कन्वेंशंस धुंधले पड़ते हैं, ऑनबोर्डिंग धीमा हो जाता है क्योंकि लोग अनुमान नहीं लगा पाते कि कहाँ देखें। रोज़मर्रा के काम में समय बढ़ता है ("इन फ़ोल्डरों में से असली कौन सा है?"), और गलतियाँ बढ़ती हैं (गलत मॉड्यूल वायर करना, गलत नामकरण उपयोग करना, लॉजिक को डुप्लिकेट करना)। टीमें अधिक समन्वय मीटिंग्स शेड्यूल करती हैं, लंबे PR स्पष्टीकरण लिखते हैं, और त्वरित दस्तावेज़ जोड़ते हैं जो जल्दी पुराने पड़ जाते हैं।
सिर्फ़ तभी अनुकूलन करें जब स्पष्ट कारण हो—और एक लिखित नोट छोड़ें।
वह नोट हल्का हो सकता है: असामान्य संरचना के पास एक छोटा कमेंट, या किसी /docs/decisions पृष्ठ में संक्षिप्त प्रविष्टि जो बताती है कि क्या बदला, क्यों बदला, और भविष्य में क्या तरीका अपनाना चाहिए।
फ़्रेमवर्क कन्वेंशंस कई पन्नों की व्याख्या हटा सकते हैं, पर वे ज़िम्मेदारी नहीं हटा देते। वे हिस्से जिन्हें अभी भी दस्तावेज़ करने की ज़रूरत है वे हैं जहाँ आपका प्रोजेक्ट जानबूझकर आम धारणा से अलग होता है।
मानक फ़्रेमवर्क व्यवहार को दोहराने से बचें। इसके बजाय उन निर्णयों को कैप्चर करें जो लोगों के दिन-प्रतिदिन काम को प्रभावित करते हैं:
उदाहरण: “हम /src/features के तहत फीचर फ़ोल्डर्स का प्रयोग करते हैं बजाय लेयर फ़ोल्डर्स (/src/components, /src/services) के क्योंकि ओनरशिप टीमों के अनुरूप मैप होती है और टीमों के बीच कपलिंग घटती है।” वह एक वाक्य हफ्तों की धीमी भटकाव को रोक सकता है।
अगर कोई अपवाद स्थानीय रूप से मायने रखता है, तो नोट स्थानीय रखें। एक छोटा README.md किसी फ़ोल्डर के अंदर, या फ़ाइल की ऊपरी परत में एक संक्षिप्त हेडर टिप्पणी अक्सर केंद्रीय विकि से बेहतर होती है जिसे कोई नहीं पढ़ता।
अच्छे उम्मीदवार:
इन नोट्स को छोटा और कार्रवाईयोग्य रखें: क्या अलग है, क्यों अलग है, और आगे क्या करना चाहिए।
एक हल्का पन्ना रखें (अक्सर /docs/project-rules.md या रूट README) जो केवल 5–10 प्रमुख चुनावों को सूचीबद्ध करे जिन्हें लोग अक्सर टोरपा सकते हैं:
यह कोई पूरा मैनुअल नहीं है—बस साझा गार्डरेल्स।
कन्वेंशंस होने के बावजूद, अगर लोग ऐप रन नहीं कर पाते तो ऑनबोर्डिंग ठहर जाती है। एक छोटा “How to run/test” सेक्शन जोड़ें जो स्टैण्डर्ड कमांड्स और आपके असल सेटअप से मेल खाता हो।
यदि पारंपरिक कमांड npm test है पर आपका प्रोजेक्ट npm run test:unit मांगता है, तो इसे स्पष्ट करें।
दस्तावेज़ तब तक सटीक रहते हैं जब उन्हें परिवर्तन का हिस्सा माना जाए। रिव्यू में पूछें: “क्या इसने नया अपवाद पेश किया?” अगर हाँ, तो उसी पुल रिक्वेस्ट में संबंधित नोट (लोकल README, Project Rules, या रूट क्विकस्टार्ट) जोड़ना आवश्यक करें।
अगर कन्वेंशंस आपके कोडबेस के “साझा डिफ़ॉल्ट्स” हैं, तो ऑटोमेशन उन्हें वास्तविक बनाता है। हर डेवलपर को विकि से नियम याद दिलाने की बजाय, आप नियम executable बना देते हैं—ताकि प्रोजेक्ट खुद को लागू करे।
एक अच्छा सेटअप ड्रिफ्ट को जल्दी और चुपचाप पकड़ता है:
*.spec.ts जैसे पैटर्न लागू करें या आवश्यक assertions को अनिवार्य करें ताकि टेस्ट पढ़ने में सुसंगत हों।ये चेक्स "कृपया याद रखें" वाले पैराग्राफ़ की जगह लेते हैं: कोड या तो कन्वेंशन के अनुसार है या नहीं।
ऑटोमेशन इसलिए बेहतर है क्योंकि यह जल्दी फेल करता है:
सबसे अच्छे नियम छोटे और साधारण होते हैं। फ़्रेमवर्क के डिफ़ॉल्ट्स से शुरू करें, फिर केवल वही जोड़ें जो स्पष्टता की रक्षा करते हों (नामकरण, संरचना, और सीमाएँ)। हर नया नियम एक और चीज़ है जिसे लोगों को समझना होगा, इसलिए नए चेक्स को तब जोड़ें जब वे लगातार समस्या हल करें और उन्हें हटाएँ जब वे मदद करना बंद कर दें।
जब एक कोडबेस फ़्रेमवर्क कन्वेंशंस का पालन करता है, टेस्ट केवल “काम कर रहा है” साबित करने से ज़्यादा कर सकते हैं। वे यह भी बता सकते हैं कि सिस्टम क्या करने वाला है, सीधे इम्प्लिमेंटेशन के पास, सरल भाषा में।
एक उपयोगी नियम: एक टेस्ट को एक व्यवहार end-to-end बताना चाहिए। अगर कोई टेस्ट नाम पढ़ कर समझ सके कि सिस्टम क्या वादा करता है, तो आपने अलग दस्तावेज़ीकरण की ज़रूरत घटा दी है।
अच्छे टेस्ट आम तौर पर एक सरल लय फॉलो करते हैं:
और नामकरण उपयोगकर्ता इरादे की नकल करता है:
signing_in_with_valid_credentials_redirects_to_dashboardcheckout_fails_when_shipping_address_is_missingये नाम "दस्तावेज़" हैं जिन्हें आप भूल कर भी अपडेट नहीं कर सकते—क्योंकि फेल होते टेस्ट बातचीत को मजबूर करते हैं।
Acceptance (या feature) टेस्ट उपयोगकर्ता के परिप्रेक्ष्य से उत्पाद कैसे व्यवहार करता है इसे दस्तावेज़ करने में श्रेष्ठ हैं।
उदाहरण प्रवाह जो acceptance tests बता सकते हैं:
ये टेस्ट प्रश्न का उत्तर देते हैं “जब मैं X करूँ तो क्या होता है?”—अक्सर नया साथी यही जानना चाहता है।
यूनिट टेस्ट तब चमकते हैं जब आपको "छोटे पर महत्वपूर्ण" नियम दस्तावेज़ करने हों:
वे विशेष रूप से मूल्यवान होते हैं जब नियम फ़्रेमवर्क कन्वेंशंस से स्पष्ट नहीं होते।
सैंपल डेटा भी जीवंत दस्तावेज़ हो सकता है। एक छोटा, अच्छी तरह नामित फ़िक्स्चर (उदा., user_with_expired_subscription) डोमेन को एक पैराग्राफ़ की तुलना में तेजी से सिखाता है।
कुंजी संयम है: फ़िक्स्चर्स को न्यूनतम, पठनीय और एक विचार से जुड़े रखें, ताकि वे भरोसेमंद उदाहरण बने रहें न कि एक अलग प्रणाली जिसे बनाए रखना पड़े।
स्टार्टर टेम्पलेट्स (और उनके पीछे के जनरेटर) “यहाँ हम कैसे करते हैं” को वास्तव में लोगों द्वारा अपनाए जाने योग्य बनाते हैं। हर टीम सदस्य से उम्मीद करने की बजाय कि वे सही फ़ोल्डर, स्क्रिप्ट, और टूलिंग याद रखें, आप उन निर्णयों को एक रेपो में बेक कर देते हैं जो सही शुरू करता है।
ये तीनों “दस्तावेज़ीकरण ऋण” घटाते हैं क्योंकि कन्वेंशन स्टार्टिंग पॉइंट में एन्कोड होते हैं, न कि किसी विकि में जो बहक जाता है।
व्यावहारिक तौर पर, यही जगह है जहाँ टूल्स जैसे Koder.ai मदद कर सकते हैं: जब आप एक नई React app, Go बैकएंड, PostgreSQL स्कीमा, या Flutter क्लाइंट जनरेट करते हैं, आप डिफ़ॉल्ट आउटपुट को अपनी कन्वेंशंस के अनुरूप कर सकते हैं (और फिर स्रोत कोड को अपने रेपो में एक्सपोर्ट कर सकते हैं)।
ऑनबोर्डिंग के दौरान ज़्यादातर भ्रम बिज़नेस लॉजिक के बारे में नहीं बल्कि यह है कि चीज़ें कहाँ रहती हैं और उन्हें कैसे चलाना है। एक अच्छा टेम्पलेट सामान्य कार्यों को हर रेपो में एक जैसा बनाता है: वही स्क्रिप्ट्स, वही फ़ोल्डर नाम, वही चेक कमांड, वही PR अपेक्षाएँ।
यदि आप कुछ नहीं करते तो कम से कम इन पर सहमति करें:
/src, /test, /docs केवल अपवादों के लिए)install + dev)test, lint, और format स्क्रिप्ट्सइसे इतना छोटा रखें कि टीमें इसे छोड़ें नहीं:
install + dev)test, lint, और format स्क्रिप्ट्ससबसे बड़ा जोखिम है कि आप एक पुराना टेम्पलेट “क्योंकि यह पिछले साल काम आया” कॉपी कर लें। पुरानी डिपेंडेंसियाँ, लेगसी स्क्रिप्ट्स, या छोड़े गए पैटर्न तब जल्दी फैला देते हैं जब वे स्टार्टर में हों।
टेम्पलेट्स को उत्पाद की तरह ट्रीट करें: उन्हें वर्ज़न करें, शेड्यूल के अनुसार रिव्यू करें, और जब आपकी कन्वेंशंस बदलें तो अपडेट करें। (यदि आपका प्लेटफ़ॉर्म snapshots और rollback सपोर्ट करता है—Koder.ai करता है—तो उन फीचर्स का उपयोग करें ताकि स्टार्टर को सुरक्षित रूप से iterate कर सकें बिना हर किसी के बेसलाइन को तोड़े)।
दस्तावेज़ कम करना लोगों को अनुमान पर छोड़ने का मतलब नहीं है। इसका मतलब है "हैप्पी पाथ" इतना सुसंगत बनाइए कि अधिकांश सवाल स्वयं ही जवाब दे दें, और केवल वास्तव में असामान्य हिस्से लिखित रहें।
उन जगहों को देखें जहाँ लोग बार-बार वही सवाल पूछते हैं Slack, PR टिप्पणियों, स्टैंडअप्स, या ऑनबोर्डिंग सत्रों में। कुछ प्रॉम्प्ट्स:
यदि आप एक ही प्रश्न दो बार सुनते हैं, तो संभावना है कि आपको अधिक prose नहीं चाहिए—आपको एक कन्वेंशन चाहिए।
प्रत्येक आवर्ती प्रश्न के लिए तय करें कि कौन सा सच है:
एक उपयोगी नियम: अगर विचलन असली समय बचा नहीं रहा या सतत जोखिम नहीं घटा रहा, तो यह संभवतः चलती समस्याएँ पैदा करेगा।
एक एकल, छोटा पेज रखें (उदा., /docs/conventions) जो सूचीबद्ध करे:
खुद को सीमित रखें: वह वही चीज़ होनी चाहिए जो किसी को पहले सप्ताह में चाहिए। यदि यह बढ़ने लगे, तो अक्सर यह संकेत है कि आपको कोडबेस को सरल बनाना चाहिए।
ऐप्स बदलते हैं। एक हल्का त्रैमासिक रिव्यू शेड्यूल करें:
जहाँ संभव हो फ़्रेमवर्क डिफ़ॉल्ट्स को प्राथमिकता दें, और केवल वही लिखें जो अलग है—साफ़, संक्षेप में, और एक जगह पर।
फ़्रेमवर्क के मानक वे डिफ़ॉल्ट पैटर्न होते हैं जिन्हें फ़्रेमवर्क उम्मीद करता है—फ़ोल्डर संरचना, नामकरण, रूटिंग, डेटा एक्सेस, और सामान्य कमांड। जब आप इन्हें अपनाते हैं, तो अन्य डेवलपर्स बिना प्रोजेक्ट-विशिष्ट दस्तावेज़ पढ़े यह अनुमान लगा सकते हैं कि चीज़ें कहाँ हैं और कैसे काम करती हैं।
क्योंकि कोडबेस बदलने के साथ प्रोजेक्ट लिखी हुई prose को प्रामाणिक रखना मुश्किल होता है। दस्तावेज़ मुख्यतः इन समस्याओं के लिए होते हैं:
कन्वेंशन पहले दो समस्याओं को कवर करते हैं क्योंकि वे संरचना को अनुमान्य बनाते हैं।
नहीं। कन्वेंशन आम चीज़ों (फ़ाइलें कहाँ जाती हैं, रूट कैसे जुड़े हैं) के बारे में लिखे गए दस्तावेज़ों की मात्रा घटाते हैं, पर आपको अभी भी प्रोजेक्ट-विशेष चीज़ें दस्तावेज़ करनी चाहिए: बिज़नेस नियम, जानबूझकर किए गए विचलन, और मुख्य निर्णय। विचार करें “कम लेकिन अधिक मूल्यवान दस्तावेज़ीकरण।”
वे रोज़मर्रा के “पहले दिन” के सवालों को मानकीकृत करते हैं:
जब कोड किसी ज्ञात पैटर्न का पालन करता है, तो डायरेक्टरी ट्री और फ़ाइल-नाम संकेतक की तरह काम करते हैं। नया सहयोगी उम्मीद के अनुसार नेविगेट कर सकता है (उदा., “templates/ में टेम्पलेट्स रहते हैं”, “migrations/ में माइग्रेशन होते हैं”)—एक लंबी आर्किटेक्चर पेज पढ़ने की बजाय।
वे कन्वेंशन को डिफ़ॉल्ट के रूप में एन्कोड करते हैं ताकि लोग स्मृति पर निर्भर न रहें। अच्छे स्कैफ़ोल्ड्स जनरेट करते हैं:
यह ड्रिफ्ट को रोकता है और फीचर-स्तर पर मैप को स्थिर रखता है।
आप तब देखेंगे जब डेवलपर्स अनुमान नहीं लगा पाते कि चीज़ें कहाँ रखी हैं या उनका नाम क्या है। आम संकेतों में शामिल हैं:
UserService बनाम UsersManager बनाम user_service)उस बिंदु पर टीम Slack स्पष्टीकरण, लंबे PR विवरण, और पुरानी क्विक-डॉक्स से समायोजित करती है।
केवल तब कस्टमाइज़ करें जब स्पष्ट लाभ हो—और फिर एक हल्का नोट छोड़ें:
README.md/docs/decisions में एक एंट्रीपकड़ो: क्या बदला, क्यों बदला, और भविष्य में क्या मानक होना चाहिए।
एक छोटा, व्यावहारिक बेसलाइन लिखें:
इन्हें संक्षिप्त रखें और जब कोई परिवर्तन नया अपवाद लाए तो कोड समीक्षा में दस्तावेज़ अपडेट करना अनिवार्य करें।
कन्वेंशन को नियमों के रूप में executable बनाइए:
जब चेक लोकल डेवलपमेंट या PR में फेल होते हैं, तो डेवलपर तुरन्त नियम सीखते हैं—और रिव्यूवर का समय शैली पर पुलिसिंग में कम लगता है।
जब ये अनुमान्य होते हैं, तो रेपो स्वयं-व्याख्यात्मक बन जाता है।