मैं रूबी / रेल एप्लिकेशन कोड पर फिर से टिप्पणी क्यों कर रहा हूं?

हैलो, मैं एक रूबी / रेल सॉफ्टवेयर डेवलपर हूं और मैं अपने (और अभी हाल ही में, विदेशी) कोड पर टिप्पणी करता हूं। दर्शकों की एक आवाज़ शायद "हैलो, डेवलपर!"

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

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

मेरी लघु कहानी का मुख्य विषय होगा: "केवल लेखक ही कोड की जटिलता का न्याय कर सकता है।"

इसलिए, सबसे पहले, आपको यह स्पष्ट करने की आवश्यकता है कि वास्तव में नियम कब काम करता है: "टिप्पणी करने के बजाय, कोड को बदल दें ताकि टिप्पणी बेमानी हो जाए।" यह केवल कुछ मामलों में काम करता है:

• जब कोड को अयोग्य रूप से लिखा जाता है: बहुत लंबा (शायद डेवलपर मानक पुस्तकालय को अच्छी तरह से नहीं जानता है और खुद बहुत अधिक अतिरिक्त कोड लिखा है) या बहुत जटिल है (एक पंक्ति में 5 से अधिक कार्यों की लंबाई के साथ कार्यों की एकल-पंक्ति श्रृंखलाएं)
• जब कोड में दिए गए पीएल तरीकों और तकनीकों के लिए शायद ही कभी इस्तेमाल किया जाता है या अप्राप्य है

और वह यह है! इन मामलों में, इस कोड को फिर से बनाना बेहतर है। Redo, सुनिश्चित करें कि कोड छोटा, स्पष्ट हो गया है, सहकर्मियों के लिए अधिक समझ में आता है और ... अंत में टिप्पणी लिखें! और इसलिए मैं पहले से ही उस जगह पर पहुंच गया जहां मैं अपने विचारों को समझाऊंगा।

आइडिया नंबर 1 के लिए स्पष्टीकरण: "केवल लेखक पर्याप्त रूप से एक कोड की जटिलता का न्याय कर सकता है।"

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

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

इस तरह एक समारोह की कल्पना करें:

 अद्यतन अपडेट करें
    सूची = current_user.lists.update (params [: id], params [: list])
 अंत

कोड सरलता नियमों के संदर्भ में, यह सिर्फ एक स्वर्ग है। यहाँ टिप्पणी करने के लिए कुछ भी नहीं है, एक पंक्ति, बिल्कुल कोई मुश्किल नहीं। हालाँकि, इस बात की कल्पना करें कि पृष्ठ पर एक साधारण रूप से नहीं, बल्कि parbone.js में जावास्क्रिप्ट कोड का उपयोग करके पैरामेट्स का गठन किया जाता है, जो कि सूचियाँ स्वयं नहीं हैं, लेकिन पिछली टीम से शेष नाम और मॉडल को अब परीक्षण में चीजें कहा जाता है। इस फ़ंक्शन को इस मॉडल के पहले_शू पर लटका दिया गया है, जो कुछ फ़ील्ड लेता है और एक लंबित कार्य बनाता है जो इन फ़ील्ड्स के डेटा के अनुसार, कुछ URL (संभवतः HTTP प्रोटोकॉल के त्रुटि नियंत्रण के बिना) को बनाता है, ताकि प्राप्त उत्तरों को फिर किसी अन्य तालिका में सहेजा जा सके। और कभी-कभी यह अपवादों को उठाता है और उनके बारे में संदेश भेजता है ... कहीं ... त्रुटि संग्रह साइट पर, जहां प्रोग्रामर को याद दिलाते ही एक्सेस दिया जाएगा। एक पूरी तरह से अलग नियंत्रक (एपीआई, उदाहरण के लिए) इन क्षेत्रों के मूल्यों को बैकबोन व्यू के लिए अजाक्स देगा। वैसे, आप यह भी स्पष्ट कर सकते हैं कि इस फ़ंक्शन को टेम्पलेट को आरएबीएल पार्सर के माध्यम से पहली बार में प्रस्तुत करना चाहिए, जो कि JSON का गठन करता है, पूरी तरह से सूची की मूल सामग्री के विपरीत, जो चीजें। ठीक है, पूरे सेट के लिए, हम स्पष्ट करते हैं कि इसे कुछ प्रतिबंधों के साथ होस्टिंग पर काम करना चाहिए, उदाहरण के लिए, क्रोन की पहुंच के बिना। और DBMS की गुणवत्ता के साथ, NoSQL का उपयोग किया जाता है।

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

एक और आम समस्या है।

प्रोजेक्ट एन में, एम की कार्यक्षमता आमतौर पर एक्सवाईजेड का उपयोग करके कार्यान्वित की जाती है। कोड को पूरी तरह से जानने के बिना या XZY द्वारा उपयोग किए गए प्रोजेक्ट डॉक्यूमेंटेशन को पढ़े बिना, डेवलपर को पता नहीं चल सकता है कि X, Y या Z पहले से उपयोग में है या नहीं। और अगर नहीं, तो इस्तेमाल क्यों नहीं किया गया। कोई प्रोग्रामर नहीं है जो तुरंत काम करना शुरू कर सकता है और एक अपरिचित परियोजना में नई चीजें बना सकता है, यह "शांत डेवलपर" के बारे में एक मिथक है। इस स्थिति में सबसे अच्छी बात यह हो सकती है कि डेवलपर अपने कार्य को सबसे अच्छे रूप में कर सकता है, वह कोड समीक्षा को दे सकता है और कोड को टिप्पणी के साथ वापस ले सकता है "यह ऐसा क्यों किया, क्योंकि हमारे लिए [कुछ तकनीकों की सूची" या "का उपयोग करना आम है" आपने ऐसा क्यों किया, क्योंकि यह इस तरह से संभव था: [उन संस्थाओं का विवरण जिनके अस्तित्व को स्वयं निर्धारित करना असंभव है (उदाहरण के लिए, उत्पादन सर्वर में डेटाबेस में ट्रिगर्स या फ़ंक्शन की उपस्थिति]]

इसलिए मैं जो सुझाव देता हूं, वह पाठक को लंबे समय तक पूछने का समय है। सबसे पहले, आप जिस कोड पर काम कर रहे हैं, उसके साथ कुछ सरल चीजें करें:

• बताएं कि यह कोड कैसे काम करता है। निश्चित रूप से, संक्षिप्त रूप से, वर्ग युक्त प्रत्येक फ़ाइल की शुरुआत में वर्णन करें कि यह क्या लागू करता है। कक्षा के तरीकों से पहले, संक्षेप में बताएं कि विधि क्या प्राप्त करती है और इसे अपने काम के अंत में क्या बनाना चाहिए, उस श्रृंखला का संक्षेप में वर्णन करें जिसके साथ डेटा पास होगा। मॉड्यूल फ़ाइलों में भी। माइग्रेशन द्वारा बनाए गए फ़ील्ड के स्वचालित रूप से परिकलित मान और असाइनमेंट पर टिप्पणी करें। फ़ंक्शन कॉल की लंबी श्रृंखला (तीन से अधिक) के मामले में, क्या कारण बनता है, की श्रृंखला का वर्णन करें, यदि केवल एक अनुक्रम।
• प्रत्येक फ़ाइल में TODO ब्लॉक दर्ज करें, उसी स्थान पर, कक्षा या मॉड्यूल की घोषणा के तुरंत बाद।
• प्रत्येक फ़ाइल में IN_WORK ब्लॉक (नाम जो भी आपको पसंद है) दर्ज करें, जिसमें आप इस बारे में लिखते हैं कि वर्तमान में किन स्थानों को फिर से काम / रिफैक्टेड / पुराना किया जा रहा है और इसके बजाय XYZ वर्ग से BLABLA का उपयोग करें।
• उन सभी तथ्यों का वर्णन करना सुनिश्चित करें, जिनकी उपस्थिति उपलब्ध दस्तावेज से नहीं काटी जा सकती है!

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

आपके ध्यान के लिए धन्यवाद और अपना कोड हमेशा स्पष्ट, सरल और प्रलेखित होने दें।