स्व-दस्तावेज कोड के 10 सिद्धांत

नमस्ते! आज मैं पीटर गुडलिफ की पुस्तक, "द क्राफ्ट ऑफ अ प्रोग्रामर // द प्रैक्टिस ऑफ राइटिंग गुड कोड" से लिया गया सही, समझने योग्य कोड लिखने के टिप्स देना चाहता हूं।

बेशक, इस मनोरंजक पुस्तक को कोई भी व्यक्ति पढ़ना पसंद करेगा जो कोड लिखता है, लेकिन उन लोगों के लिए जो विशेष रूप से आलसी हैं, लेकिन जो कम पीड़ा को रोकना चाहते हैं और अपने सहयोगियों को गुमराह करना चाहते हैं ( एक विवेक है ), मैं बिल्ली के तहत स्व-दस्तावेजीकरण कोड के 10 सिद्धांत प्रस्तुत करता हूं :

1. अच्छे फॉर्मेटिंग के साथ सरल कोड लिखें

कोड को समझने में आसानी पर प्रस्तुति प्रारूप का बहुत प्रभाव पड़ता है। एक उचित प्रतिनिधित्व कोड की संरचना को बताता है: फ़ंक्शन, लूप, और सशर्त बयान स्पष्ट हो जाते हैं।

int fibonacci(int position) { if (position < 2) { return 1; } int previousButOne = 1; int previous = 1; int answer = 2; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } return answer; } 

• सुनिश्चित करें कि आपके कोड का सामान्य निष्पादन स्पष्ट है। सामान्य हैंडलिंग अनुक्रम से त्रुटि से निपटने में बाधा नहीं होनी चाहिए। सशर्त यदि तत्कालीन अन्य निर्माणों में एक समान शाखा क्रम होना चाहिए (उदाहरण के लिए, हमेशा "त्रुटि हैंडलिंग शाखा", या इसके विपरीत "नियमित" कोड शाखा रखें)।
• नेस्टेड स्टेटमेंट के बहुत सारे स्तरों से बचें। अन्यथा, कोड जटिल हो जाता है और व्यापक स्पष्टीकरण की आवश्यकता होती है। यह आमतौर पर स्वीकार किया जाता है कि प्रत्येक फ़ंक्शन में केवल एक निकास बिंदु होना चाहिए; इसे सिंगल एंट्री, सिंगल एक्ज़िट (एसईएसई, वन इनपुट, वन आउटपुट) कोड के रूप में जाना जाता है। लेकिन आमतौर पर यह प्रतिबंध कोड को पढ़ना मुश्किल बनाता है और घोंसले के शिकार के स्तर को बढ़ाता है। मैं निम्नलिखित SESE -style विकल्प की तुलना में ऊपर के फंक्शन फंक्शन विकल्प को पसंद करता हूं:
  
  

   int fibonacci(int position) { int answer = 1; if (position >= 2) { int previousButOne = 1; int previous = 1; for (int n = 2; n < position; ++n) { previousButOne = previous; previous = answer; answer = previous + previousButOne; } } return answer; } 

  
  मैं अतिरिक्त रिटर्न स्टेटमेंट के पक्ष में इस तरह के अत्यधिक घोंसले के शिकार को मना करूंगा - यह फ़ंक्शन को पढ़ने के लिए बहुत अधिक कठिन हो गया है। समारोह में कहीं गहरे लौटने की आशंका अत्यधिक संदिग्ध है, लेकिन इसकी शुरुआत में सरल संक्षिप्त गणना पढ़ने को बहुत आसान बना देती है।
• कोड ऑप्टिमाइज़ेशन से सावधान रहें जो अंतर्निहित एल्गोरिथम में स्पष्टता का कारण बनता है। अपना कोड तभी चुनें जब यह स्पष्ट हो जाए कि यह स्वीकार्य कार्यक्रम प्रदर्शन में हस्तक्षेप करता है। अनुकूलन करते समय, कोड के इस अनुभाग के कामकाज के बारे में स्पष्ट टिप्पणी करें।

2. सार्थक नाम चुनें

सभी चर, प्रकार, फाइलें और कार्यों के नाम सार्थक होने चाहिए और भ्रामक नहीं। नाम सही ढंग से वर्णन करना चाहिए कि यह क्या है। यदि आप एक सार्थक नाम नहीं खोज पा रहे हैं, तो इस बारे में संदेह है कि क्या आप अपने कोड के संचालन को समझते हैं।

नामकरण प्रणाली सुसंगत होनी चाहिए और अप्रिय आश्चर्य का कारण नहीं होनी चाहिए। सुनिश्चित करें कि चर हमेशा उस उद्देश्य के लिए उपयोग किया जाता है जो उसका नाम बताता है।

नामों का एक अच्छा विकल्प संभवतः अनावश्यक टिप्पणियों से बचने का सबसे अच्छा तरीका है। प्राकृतिक भाषाओं की अभिव्यंजना के लिए कोड को लाने के लिए नाम सबसे अच्छा तरीका है।

3. स्वतंत्र कार्यों में कोड को तोड़ें

आप कोड को फ़ंक्शन में कैसे तोड़ते हैं और आप उन्हें क्या नाम देते हैं, इससे कोड समझ में आता है या पूरी तरह से समझ में नहीं आता है।

• एक कार्य, एक क्रिया

किसी भी अप्रत्याशित दुष्प्रभाव को कम करें, चाहे वे कितने ही उपयोगी क्यों न लगें। उन्हें अतिरिक्त दस्तावेज की आवश्यकता होगी।
छोटे कार्य लिखें। उन्हें समझना आसान है। आप एक जटिल एल्गोरिथ्म में नेविगेट कर सकते हैं यदि इसे सार्थक नामों के साथ छोटे टुकड़ों में विभाजित किया गया है, लेकिन यह कोड के आकारहीन द्रव्यमान में नहीं किया जा सकता है।

4. सार्थक प्रकार के नाम चुनें

संभव हद तक, उपलब्ध भाषा सुविधाओं का उपयोग करके सीमाओं या व्यवहार का वर्णन करें। उदाहरण के लिए:

• एक मूल्य निर्धारित करते समय जो नहीं बदलेगा, उसे एक निरंतर प्रकार असाइन करें (C में कॉन्स्ट का उपयोग करें)।
• यदि चर को नकारात्मक मान नहीं लेना चाहिए, तो अहस्ताक्षरित प्रकार का उपयोग करें (यदि यह भाषा में मौजूद है)।
• संबंधित डेटासेट का वर्णन करने के लिए गणना का उपयोग करें।
• चर के प्रकार को सही ढंग से चुनें। C / C ++ में, type size_t के चर को आकार लिखें, और अंक के साथ अंकगणितीय संचालन के परिणाम को ptrdiff_t के चर के रूप में लिखें।

5. नामित स्थिरांक का उपयोग करें

अगर (काउंटर == 76) कोड समान है। 76 का जादुई अर्थ क्या है? इस जाँच का अर्थ क्या है? जादू की संख्याओं का अभ्यास शातिर है। वे कोड का अर्थ अस्पष्ट करते हैं। इस तरह लिखना बेहतर है:

 const size_t bananas_per_cake = 76; ... if (count == bananas_per_cake) { //    } 

यदि लगातार 76 कोड अक्सर कोड में पाया जाता है (मुझे क्षमा करें, bananas_per_cake ), तो एक अतिरिक्त लाभ प्राप्त होता है: जब पाई में केले की सामग्री को बदलना आवश्यक होता है, तो कोड को एक स्थान पर संशोधित करने के बजाय, एक वैश्विक खोज / संख्या 76 का परिवर्तन करने के लिए पर्याप्त है, जो त्रुटियों से भरा है।

यह न केवल संख्याओं पर लागू होता है, बल्कि निरंतर तारों पर भी लागू होता है। अपने कोड में किसी भी शाब्दिक को देखें, खासकर यदि वे बार-बार आते हैं। इसके बजाय नामांकित स्थिरांक का उपयोग करना बेहतर नहीं होगा?

6. कोड के महत्वपूर्ण टुकड़ों को हाइलाइट करें

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

• विज्ञापनों को बुद्धिमानी से कक्षा में रखें। सबसे पहले, खुली वस्तुओं के बारे में जानकारी जानी चाहिए, क्योंकि यह उस वर्ग का उपयोगकर्ता है जिसे इसकी आवश्यकता है। बंद कार्यान्वयन विवरण को अंत में रखा जाना चाहिए, क्योंकि वे अधिकांश पाठकों के लिए कम दिलचस्प नहीं हैं।
• यदि संभव हो, तो सभी गैर-आवश्यक जानकारी छिपाएँ। वैश्विक नाम स्थान में अनावश्यक कचरा न छोड़ें। C ++ में आइडियल पिंपल है, जो आपको कक्षा के कार्यान्वयन के विवरण को छिपाने की अनुमति देता है। (मेयर्स 97)।
• महत्वपूर्ण कोड छिपाएं नहीं। एक पंक्ति में एक से अधिक कथन न लिखें और इस कथन को सरल बनाएं। भाषा आपको लूप के लिए बहुत सरल बयान लिखने की अनुमति देती है, जिसमें सभी तर्क कई कॉमा की मदद से एक पंक्ति में फिट होते हैं, लेकिन ऐसे बयानों को पढ़ना मुश्किल होता है। इनसे बचें।
• सशर्त बयानों की घोंसले की गहराई को सीमित करें। अन्यथा, इफ और कोष्ठकों के ढेर के पीछे वास्तव में महत्वपूर्ण मामलों की हैंडलिंग को नोटिस करना मुश्किल है।

7. संबंधित डेटा को मिलाएं

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

यदि संभव हो, तो भाषा निर्माण का उपयोग करके वस्तुओं को मिलाएं। C ++ और C # में, आप तत्वों को समान नामस्थान के साथ जोड़ सकते हैं। जावा में, बंडल तंत्र पैकेज इंजन है। संबंधित स्थिरांक को एक गणना में परिभाषित किया जा सकता है।

8. लेबल फाइलें

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

 /********************************************************* * File: Foo.java * Purpose: Foo class implementation * Notice: (c) 1066 Foo industries. All rights reserved. ********************************************************/ 

9. त्रुटियों को सही ढंग से संभालें

सबसे उपयुक्त संदर्भ में सभी त्रुटियों से निपटना। यदि डिस्क पर पढ़ने / लिखने की समस्या है, तो इसे उस कोड में संसाधित किया जाना चाहिए जो डिस्क तक पहुंच से संबंधित है। इस त्रुटि को संभालने के लिए, आपको एक अन्य त्रुटि (जैसे अपवाद "मुझे फ़ाइल लोड नहीं कर सकता") उत्पन्न करने की आवश्यकता हो सकती है, इसे उच्च स्तर पर पास करना। इसका मतलब यह है कि कार्यक्रम के प्रत्येक स्तर पर, त्रुटि को इसके संदर्भ में समस्या का सटीक वर्णन होना चाहिए। यह उपयोगकर्ता इंटरफ़ेस कोड में डिस्क विफलता से जुड़ी त्रुटि को संभालने के लिए कोई मतलब नहीं है।

स्व-दस्तावेजीकरण कोड पाठक को यह समझने में मदद करता है कि त्रुटि कहां हुई, इसका क्या अर्थ है और इस समय कार्यक्रम के लिए इसके परिणाम क्या हैं।

10. सार्थक टिप्पणी लिखिए

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

पहले अन्य ट्रिक आजमाएं। उदाहरण के लिए, जांचें कि क्या आप कोड को नाम बदलकर या सहायक फ़ंक्शन बनाकर अधिक स्पष्ट कर सकते हैं, और इस प्रकार टिप्पणी करने से बचें।

---

मुझे यकीन है कि इनमें से कई सिद्धांतों को आदत में लाने के बाद, आप एक प्रोग्रामर को खुश करेंगे। और आप इस खुश प्रोग्रामर होंगे। कब? छह महीने पहले अपने कोड पर काम पर लौटने के समय।