358 रीडिंग

अपने आप को सिरदर्द से बचाएं और सही तरीके से अनुबंधों को दस्तावेज़ करें

द्वारा Ilia Menshikov7m2023/02/16

बहुत लंबा; पढ़ने के लिए

समझौते सॉफ्टवेयर विकास का एक अनिवार्य हिस्सा हैं। वे विकास लागत कम करते हैं और डेवलपर्स के जीवन को आसान बनाते हैं। लेकिन एक समस्या है - वे अक्सर चीजों को जटिल बनाते हैं क्योंकि वे ठीक से प्रलेखित नहीं होते हैं। इस लेख में, मैं आपको करारों के दस्तावेज़ीकरण का *सही तरीका* बताऊँगा।

featured image - अपने आप को सिरदर्द से बचाएं और सही तरीके से अनुबंधों को दस्तावेज़ करें

समझौते सॉफ्टवेयर विकास का एक अनिवार्य हिस्सा हैं। वे विकास लागत कम करते हैं और डेवलपर्स के जीवन को आसान बनाते हैं। लेकिन एक समस्या है - वे अक्सर चीजों को जटिल करते हैं क्योंकि वे ठीक से प्रलेखित नहीं होते हैं और पुरानी परियों की कहानियों की तरह मौखिक रूप से टीम में नहीं पहुंचाए जाते हैं। फैलते-फैलते समझौते बदल जाते हैं। अचानक, नए विवरण प्रकट होते हैं और पुराने चले जाते हैं। अंत तक, टीम के प्रत्येक सदस्य के दिमाग में अपनी सहमति की तस्वीर होती है, और वह तस्वीर भी कभी-कभी फीकी पड़ जाती है।

इससे भी बदतर - जब टीमें इन समझौतों का दस्तावेजीकरण शुरू करती हैं, तो वे इसे बेतरतीब ढंग से करते हैं और अक्सर ढीले-ढाले दस्तावेजों की गड़बड़ी पैदा करते हैं, जिनमें से आधे भी अप-टू-डेट नहीं होते हैं।

इस लेख में, मैं आपको अनुबंधों के दस्तावेज़ीकरण का सही तरीका बताऊँगा, जिससे वे आपकी मदद करेंगे।

तो, हम समझौतों को कैसे मददगार बना सकते हैं? हमें न केवल उन्हें प्रलेखित करना है बल्कि यह भी करना है ताकि:

उनका उपयोग करना आसान था;
इन समझौतों का पालन करने के लिए न्यूनतम प्रयास की आवश्यकता थी;
यह समझना आसान होगा कि क्या ये समझौते अभी भी मान्य हैं;
यह समझना आसान होगा कि ये समझौते क्यों मौजूद हैं;
आदर्श रूप से - वे स्वचालित थे।

समझौतों को वर्गीकृत करने के लिए बहुत सारे तरीके सामने आ सकते हैं। मैं उन्हें उनके अमूर्त स्तर से विभाजित करूँगा:

कोड-स्तरीय समझौते;
वास्तुकला-स्तर के समझौते;
प्रक्रिया-स्तर के समझौते।

अलग-अलग स्तरों पर होने वाले समझौतों के लिए अलग-अलग तरीकों की आवश्यकता होती है ताकि उन्हें दस्तावेजित किया जा सके और अलग-अलग लाभ मिल सकें। आइए प्रत्येक स्तर पर एक नज़र डालें।

कोड-स्तरीय सम्मेलन

इन समझौतों का उद्देश्य कोड को एक समान, व्यापक और पठनीय बनाना है। यहां कुछ उदाहरण दिए गए हैं:

हम सिंगल के बजाय डबल कोट्स का उपयोग करते हैं।
Config क्लास को छोड़कर हम कोड से सीधे ईएनवी को कॉल नहीं करते हैं, जहां हम इन कॉल को तरीकों में लपेटते हैं।
सेवा वस्तुओं में पोस्टफ़िक्स Service और एक सार्वजनिक विधि call ।

इस प्रकार के समझौते पाठक के संज्ञानात्मक भार को कम करने के लिए बनाए जाते हैं और उसे अज्ञात कोड के लिए तेजी से अभ्यस्त होने में मदद करते हैं। जैसे मार्टिन ने कहा, कोड लिखे जाने की तुलना में 10 गुना अधिक पढ़ा जाता है।

रूबी ऑन रेल्स फ्रेमवर्क पर आपकी राय के बावजूद - इसके मूल में convention over configuration है, जो किसी भी रेल डेवलपर को किसी और की परियोजना को खोलने और तुरंत इसे बहुत अच्छी तरह से नेविगेट करने की अनुमति देता है।

तो इन सम्मेलनों का दस्तावेजीकरण कैसे करें? लिंटर टूल! यदि कोई उपयुक्त लिंटर नियम नहीं है, तो अपना स्वयं का लिंट लिखें। लगभग हर लिंटर आपको ऐसा करने की अनुमति देता है: यहाँ में एक उदाहरण है, और यहाँ के लिए है।

ऐसे सम्मेलनों के लिए लिंटर का उपयोग करने से आपको तीन लाभ मिलते हैं:

किसी डेवलपर को उनके बारे में सोचने की कोई आवश्यकता नहीं है - लिंटर हर त्रुटि को उजागर करेगा और अक्सर उन्हें आपके लिए ठीक भी कर देगा।
यदि आप अपनी टीम में कोड समीक्षाओं का उपयोग करते हैं - तो आप अपने समीक्षकों को इन चीज़ों के बारे में सोचने से मुक्त करते हैं और उन्हें अधिक महत्वपूर्ण चीज़ों को देखने के लिए अधिक समय देते हैं।
डेवलपर को विकास चक्र की शुरुआत में ही समस्या दिखाई देगी, इसलिए वह बाद में संदर्भ पर वापस जाने के लिए समय बर्बाद किए बिना इसे तुरंत ठीक कर देगा। समझौता रखना सस्ता हो जाता है।

एक और बोनस: एक नया लिंटर नियम लिखना एक जूनियर डेवलपर के लिए उत्कृष्ट प्रशिक्षण है। इस कार्य को पूरा करने के दौरान, वह कोड पार्सिंग और एएसटी के निर्माण के बारे में बहुत कुछ सीखेंगे और भाषा को और गहराई से समझेंगे।

आर्किटेक्चर-स्तर के सम्मेलन

यह एक उच्च-स्तरीय प्रकार का समझौता है जिसका उद्देश्य आपकी वास्तुकला को विचारशील, सुसंगत और एकसमान बनाना है। कुछ उदाहरण:

हम नियमित सेवाओं को लिखने के लिए पायथन का उपयोग करते हैं और सिस्टम के अत्यधिक लोड वाले हिस्सों में एलिक्सिर का उपयोग करते हैं।
बैकएंड वर्णित प्रारूप में त्रुटियां लौटाता है।
प्रोमेथियस में मेट्रिक्स भेजने के लिए प्रत्येक सेवा की आवश्यकता होती है, /metrics समापन बिंदु पर, मेट्रिक्स भेजने के लिए पोर्ट PROMETHEUS_PORT पर्यावरण चर द्वारा कॉन्फ़िगर किया गया है।

इस तरह के समझौते न केवल संज्ञानात्मक भार को कम करते हैं बल्कि तीन और समस्याओं को भी हल करते हैं:

परिचालन लागत कम करें। यदि सेवाओं को उसी तरह से लॉन्च किया जाता है, समान लॉग प्रारूप के साथ, समान मेट्रिक्स प्रकाशित करते हुए, तो सेवा को बनाए रखना और घटनाओं का सामना करना बहुत आसान हो जाता है।
डिजाइन की लागत कम करें। डेवलपर को हर बार स्क्रैच से आर्किटेक्चर डिजाइन करने की आवश्यकता नहीं है - आपने पहले से सोचा था, और अब उसे बुनियादी चीजों की चिंता किए बिना केवल एक विशिष्ट सुविधा या सेवा को डिजाइन करने की आवश्यकता है।
संचार लागत कम करें। यदि काफ्का में सर्वर की प्रतिक्रिया या घटना का प्रारूप पूर्व निर्धारित है, तो डेवलपर्स को हर बार अपनी बातचीत पर चर्चा करने की आवश्यकता नहीं होती है, इसके बजाय वे केवल सम्मेलन का उल्लेख कर सकते हैं।

इस तरह के समझौते अधिक जटिल होते हैं, और मैं उन्हें दो चरणों में तय करना पसंद करता हूं।

चरण 1 - वर्णन करें

आर्किटेक्चर डिसीजन रिकॉर्ड (एडीआर) ऐसे समझौतों के दस्तावेजीकरण के लिए एक उपकरण है। इसका आकर्षण यह है कि यह एक समझौते के साथ-साथ मेटा जानकारी को कैप्चर करता है: ऐसा समझौता क्यों अपनाया गया; किन विकल्पों पर चर्चा हुई; जब इसे अंतिम बार संशोधित किया गया था; क्या समझौता अभी भी वैध है?

यह टीम के नए सदस्य को किए गए निर्णयों के कारणों को समझने और आसपास के लोगों से इसके बारे में नहीं पूछने की अनुमति देता है।

एडीआर में कई मुख्य ब्लॉक होते हैं:

समझौता किस समस्या का समाधान करता है?
समस्या को हल करने के लिए किन विकल्पों पर विचार किया गया और उनके पक्ष और विपक्ष क्या थे?
अंत में कौन सा विकल्प चुना गया?

अतिरिक्त ब्लॉक हो सकते हैं - उदाहरण के लिए, कार्यान्वयन लागत की गणना।

एडीआर को एक ऐसी प्रणाली में रखना अधिक सुविधाजनक है जहां कोई परिवर्तन और चर्चाओं का इतिहास देख सकता है। मेरी पसंद गीथब और धारणा है, प्रत्येक इसके पेशेवरों और विपक्षों के साथ है। जीथब का लाभ यह है कि इसमें एक समीक्षा उपकरण और संस्करण इतिहास बॉक्स से बाहर है। डेटाबेस और टैग के साथ काम करने की सुविधा के कारण धारणा एक अच्छा समाधान हो सकती है। और यह भी - गैर-डेवलपर्स इसे आसानी से संभाल सकते हैं।

यदि आप ADR के साथ आरंभ करना चाहते हैं, तो मैं को देखने की सलाह देता हूं, जहां आप विभिन्न ADR टेम्प्लेट और उनका उपयोग करने के उदाहरण पा सकते हैं।

चरण 2 - स्वचालित

कोड-स्तरीय सम्मेलनों की तुलना में ADR को स्वचालित करना अधिक चुनौतीपूर्ण है: डिज़ाइन लिंटर का अभी तक आविष्कार नहीं हुआ है (क्या अफ़सोस है!) फिर भी, उन्हें आंशिक रूप से स्वचालित करना संभव है, यह इस बात पर निर्भर करता है कि यह किस प्रकार का समझौता है।

भाषाओं, पुस्तकालयों और इंफ्रास्ट्रक्चर में एम्बेडिंग सेवाओं पर समझौतों के लिए सर्विस टेम्प्लेट बनाएं और अपडेट करें। तब डेवलपर स्क्रैच से नई सेवाएं नहीं लिखेगा, बल्कि इसे टेम्प्लेट से कॉपी करेगा और तुरंत कॉन्फ़िगर किए गए डॉकरफाइल, मेट्रिक्स पब्लिशिंग आदि प्राप्त करेगा।

इसी तरह, आप एक एप्लिकेशन में क्लास जनरेटर बना सकते हैं। मान लीजिए कि आप कई एप्लिकेशन लेयर्स (कंट्रोलर => फॉर्म => सर्विस ऑब्जेक्ट) पर सहमत हुए हैं। उस स्थिति में, आप एक साधारण कंसोल कमांड बना सकते हैं जो एक ही बार में एक नई सुविधा के लिए सभी परतें उत्पन्न करेगा।

यदि आप कुछ सिद्धांतों पर सहमत हैं जो इस तरह से स्वचालित नहीं हो सकते हैं, तो आप चेकलिस्ट को व्यवस्थित कर सकते हैं जो स्वचालित रूप से मर्ज अनुरोध या ट्रैकर में किसी कार्य में जुड़ जाते हैं; इस प्रकार, कार्य को आगे बढ़ाने से पहले डेवलपर जल्दी से उनके माध्यम से जा सकता है।

प्रक्रिया-स्तर के समझौते

प्रत्येक कंपनी में प्रक्रियाओं के लिए कई समझौते होते हैं, उदाहरण के लिए:

कंपनी में काम पर रखने के तरीके का विवरण।
रिलीज़ रोलआउट प्रक्रिया का विवरण.
बड़े कार्यों के लिए डिजाइन समीक्षा की आवश्यकता।
वर्तमान कार्यों और बाधाओं की चर्चा के साथ सप्ताह में दो बार टीम मीटिंग आयोजित करना।

कुछ समय पहले तक, मैंने इन समझौतों के दस्तावेजीकरण के बारे में नहीं सोचा था, हालाँकि वे कंपनी की सफलता को महत्वपूर्ण रूप से प्रभावित करते हैं। इन समझौतों के दस्तावेज़ीकरण से न केवल ऊपर वर्णित प्रकारों के लाभ होते हैं, बल्कि आपको प्रक्रियाओं को युक्तिसंगत बनाने, उन्हें दृश्यमान विमान में स्थानांतरित करने और उनकी समीचीनता के बारे में सोचने की भी अनुमति मिलती है।

मुझे से विचार मिला। उन्होंने ADR - प्रोसेस डिसीजन रिकॉर्ड (PDR) के समान एक उपकरण प्रस्तावित किया। फर्क सिर्फ इतना है कि वास्तु निर्णयों के बजाय, यह प्रक्रियाओं के बारे में निर्णयों का वर्णन करता है। इसके अलावा, उन्होंने प्रत्येक पीडीआर में एक "पुनर्विचार तिथि" डालने का सुझाव दिया - एक तिथि जब आप दस्तावेज़ पर लौटते हैं यह देखने के लिए कि क्या यह अभी भी आपकी समस्याओं को सर्वोत्तम तरीके से हल करता है, गोद लेने के n महीने बाद (वैसे, वही किया जा सकता है) एडीआर के साथ)।

स्वचालन के लिए, आप बहुत कम कर सकते हैं। आप जिरा में वर्कफ़्लो सेट करके, मीटिंग्स के लिए रिमाइंडर सेट करके या एक बॉट बनाकर कुछ प्रक्रियाओं को स्वचालित कर सकते हैं जो स्वचालित रूप से सप्ताह के परिणामों की प्रस्तुति तैयार करता है (हालांकि, मैंने यह एक विदेशी कंपनी में किया था)।

लेकिन अक्सर, आप वास्तव में प्रक्रियाओं को स्वचालित नहीं कर सकते हैं, और आपका मुख्य लक्ष्य उनका अनुसरण न करने की तुलना में उनका पालन करना आसान बनाना है। फिर भी, समझौतों का दस्तावेजीकरण अभी भी मददगार होगा, भले ही आपकी प्रक्रियाओं का पालन करना पहले से ही आसान हो - औपचारिकता और युक्तिकरण आपको उन्हें सुधारने की अनुमति देगा।

तो, परिणाम क्या है?

दस्तावेज़ीकरण और बाद में स्वचालन फायदेमंद हैं: विकास पर खर्च किया गया समय कम हो जाता है, अनुप्रयोग अधिक सहायक हो जाते हैं, और प्रक्रियाएँ स्मार्ट हो जाती हैं।

कोई सोच सकता है कि यह सब अनावश्यक नौकरशाही है क्योंकि "हम अच्छे लोग हैं - हम इसके बिना कोड विकसित कर सकते हैं।" लेकिन वास्तव में, समझौते आपके समय और धन की पर्याप्त मात्रा की बचत करेंगे और कर्मचारियों की तंत्रिका कोशिकाओं की रक्षा करेंगे। निश्चित रूप से, आपको पूरी तरह से निपटने और समझौतों के खिलाफ जाने वाली किसी भी चीज़ को अस्वीकार करने की आवश्यकता नहीं है - यह एक संकेत हो सकता है कि समझौते को अद्यतन करने की आवश्यकता है या आपने शुरू में इसके कुछ पहलुओं के बारे में नहीं सोचा था।

यदि आपने अभी तक अपनी टीम में समझौतों का दस्तावेजीकरण शुरू नहीं किया है, तो निम्न अमूर्त स्तरों से उच्चतर स्तर पर जाएँ: कोड-स्तर के समझौतों से शुरू करें, फिर आर्किटेक्चर-स्तर, और उसके बाद ही प्रक्रिया-स्तर का सामना करें। अनुबंध दस्तावेज़ आपकी टीम में विकसित करने की आदत है, और कम अमूर्त अवधारणाओं के साथ शुरुआत करना बहुत आसान है।

इसके अलावा, लेख में सभी प्रकारों का वर्णन नहीं किया गया है। उदाहरण के लिए, आप डिज़ाइन अनुबंध को लाइब्रेरी घटकों के रूप में दस्तावेज़ित कर सकते हैं।

प्रत्येक नए प्रकार का समझौता उन्हीं तीन चरणों से होकर गुजरता है:

यह पता करें कि इसे कैसे प्रलेखित किया जाए।
इसे स्वचालित करने का तरीका जानें।
जैसे-जैसे समय बीतता है, यह सुनिश्चित करें कि इसे रखने में लगने वाले संसाधनों की तुलना में यह अधिक संसाधनों की बचत करता है।

और एक पिछे। प्रलेखन प्रक्रिया के दौरान, यह पाया जा सकता है कि कुछ मौजूदा समझौते स्पष्ट रूप से किसी भी तरह से उचित नहीं हैं, आपकी टीम का समय बर्बाद करते हैं, और आम तौर पर हानिकारक होते हैं, लेकिन आप पहले से ही उनके अभ्यस्त हैं। इस मामले में, आपको टीम के मन में आदत की बाधा को दूर करना होगा और अपनी टीम को यह विश्वास दिलाना होगा कि समझौतों की अस्वीकृति कभी-कभी उन्हें स्वीकार करने से अधिक महत्वपूर्ण होती है। लेकिन यह बिल्कुल अलग कहानी है।

भी प्रकाशित हुआ।