व्यायाम - प्रभावी कोड टिप्पणियां बनाएं

पूरा किया

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

एक कोड टिप्पणी क्या है?

एक कोड टिप्पणी संकलक को वर्तमान पंक्ति में कोड टिप्पणी प्रतीकों के बाद सब कुछ अनदेखा करने का निर्देश है।

// This is a code comment!

यह पहली बार में उपयोगी नहीं लग सकता है, लेकिन यह तीन स्थितियों में उपयोगी है:

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

नोट

कोड टिप्पणियों का उपयोग यह कहने के लिए किया जाना चाहिए कि कोड क्या नहीं कर सकता है। अक्सर, डेवलपर्स अपना कोड अपडेट करते हैं लेकिन कोड टिप्पणियों को अपडेट करना भूल जाते हैं। उच्च-स्तरीय विचारों के लिए टिप्पणियों का उपयोग करना और कोड की एक व्यक्तिगत पंक्ति कैसे काम करती है, इसके बारे में टिप्पणियों को जोड़ना सबसे अच्छा नहीं है।

अपना कोडिंग वातावरण तैयार करें

इस मॉड्यूल में ऐसे अभ्यास शामिल हैं जो नमूना कोड बनाने और चलाने की प्रक्रिया के माध्यम से आपका मार्गदर्शन करते हैं। आपको अपने विकास परिवेश के रूप में Visual Studio Code का उपयोग करके इन गतिविधियों को पूरा करने के लिए प्रोत्साहित किया जाता है। इन गतिविधियों के लिए Visual Studio Code का उपयोग करने से आपको विश्वभर के पेशेवरों द्वारा उपयोग किए जाने वाले डेवलपर परिवेश में कोड लिखने और चलाने में अधिक सहज बनने में मदद मिलेगी.

1. Visual Studio कोड खोलें।

   Visual Studio कोड खोलने के लिए आप Windows प्रारंभ मेनू (या किसी अन्य OS के लिए समकक्ष संसाधन) का उपयोग कर सकते हैं।

2. Visual Studio कोड फ़ाइल मेनू पर, खोलें फ़ोल्डर का चयन करें।

3. फ़ोल्डर खोलें संवाद में, Windows डेस्कटॉप फ़ोल्डर में नेविगेट करें.

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

4. फ़ोल्डर खोलें संवाद में, फ़ोल्डर का चयन करें का चयन करें.

   यदि आपको यह पूछने वाला सुरक्षा संवाद दिखाई देता है कि क्या आप लेखकों पर विश्वास करते हैं, तो हाँ चुनें.

5. Visual Studio कोड टर्मिनल मेनू पर, नया टर्मिनल का चयन करें।

   ध्यान दें कि टर्मिनल पैनल में एक कमांड प्रॉम्प्ट वर्तमान फ़ोल्डर के लिए फ़ोल्डर पथ प्रदर्शित करता है। उदाहरण के लिए:

   C:\Users\someuser\Desktop>
   

   नोट

   यदि आप सैंडबॉक्स या होस्ट किए गए वातावरण के बजाय अपने स्वयं के PC पर कार्य कर रहे हैं और आपने इस C# श्रृंखला में अन्य Microsoft Learn मॉड्यूल पूर्ण कर लिए हैं, तो हो सकता है कि आपने कोड नमूनों के लिए पहले से ही कोई प्रोजेक्ट फ़ोल्डर बना लिया हो. यदि ऐसा है, तो आप अगले चरण को छोड़ सकते हैं, जिसका उपयोग TestProject फ़ोल्डर में कंसोल ऐप बनाने के लिए किया जाता है।

6. टर्मिनल कमांड प्रॉम्प्ट पर, निर्दिष्ट फ़ोल्डर में एक नया कंसोल अनुप्रयोग बनाने के लिए, निम्न संकेत दर्ज करें:

   dotnet new console -o ./CsharpProjects/TestProject
   

   यह .NET CLI आदेश निर्दिष्ट फ़ोल्डर स्थान में एक नया C# कंसोल अनुप्रयोग प्रोजेक्ट बनाने के लिए .NET प्रोग्राम टेम्पलेट का उपयोग करता है। आदेश आपके लिए CsharpProjects और TestProject फ़ोल्डर बनाता है, और आपकी .csproj फ़ाइल के नाम के रूप में TestProject का उपयोग करता है।

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

7. EXPLORER दृश्य में, CsharpProjects फ़ोल्डर का विस्तार करें।

   आप TestProject फ़ोल्डर और दो फ़ाइलें, Program.cs नामक एक C# प्रोग्राम फ़ाइल और TestProject.csproj नामक C# प्रोजेक्ट फ़ाइल देखना चाहिए।

8. Visual Studio कोड फ़ाइल मेनू पर, खोलें फ़ोल्डर का चयन करें।

9. फ़ोल्डर खोलें संवाद में, CsharpProjects फ़ोल्डर का चयन करें, और उसके बाद फ़ोल्डर का चयन करेंका चयन करें।

10. EXPLORER दृश्य में, TestProject फ़ोल्डर का विस्तार करें, और उसके बाद Program.cs का चयन करें।

11. मौजूदा कोड पंक्तियों को हटाएँ।

    आप इस मॉड्यूल के दौरान कोड नमूने बनाने, बनाने और चलाने के लिए इस सी # कंसोल प्रोजेक्ट का उपयोग करेंगे।

12. टर्मिनल पैनल बंद करें।

कोड टिप्पणियाँ बनाएँ और उनका उपयोग करें

इस कार्य में, आप विभिन्न प्रकार की कोड टिप्पणियाँ बनाएँगे और निकालेंगे.

1. Visual Studio कोड संपादक पैनल में, निम्न कोड दर्ज करें:

   string firstName = "Bob";
   int widgetsSold = 7;
   Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
   

2. कोड टिप्पणियों और संशोधनों के साथ अपने कोड को संशोधित करने के लिए, निम्नानुसार अपना कोड अपडेट करें:

   string firstName = "Bob";
   int widgetsPurchased = 7;
   // Testing a change to the message.
   // int widgetsSold = 7;
   // Console.WriteLine($"{firstName} sold {widgetsSold} widgets.");
   Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
   

3. अपनी टिप्पणियों और कोड अपडेट की समीक्षा करने के लिए एक मिनट का समय लें।

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

4. Visual Studio कोड फ़ाइल मेनू पर, सहेजेंक्लिक करें।

5. EXPLORER दृश्य में, अपने TestProject फ़ोल्डर स्थान पर कोई टर्मिनल खोलने के लिए, TestProjectराइट-क्लिक करें, और उसके बाद एकीकृत टर्मिनल में खोलेंका चयन करें।

6. टर्मिनल कमांड प्रॉम्प्ट परडॉटनेट चलाएँटाइप करें, और उसके बाद Enter दबाएँ।

   आपको निम्न आउटपुट देखना चाहिए:

   Bob purchased 7 widgets.
   

   दोबारा, यदि आप अपने अपडेट से संतुष्ट हैं, तो टिप्पणी किए गए पुराने कोड को हटा दें।

7. कोड टिप्पणियाँ हटाएँ।

   आपका कोड निम्न से मेल खाना चाहिए:

   string firstName = "Bob";
   int widgetsPurchased = 7;
   Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
   

8. एक ब्लॉक टिप्पणी लागू करने के लिए जो कई पंक्तियों पर टिप्पणी करता है, अपने कोड को निम्नानुसार अपडेट करें:

   /*
   string firstName = "Bob";
   int widgetsPurchased = 7;
   Console.WriteLine($"{firstName} purchased {widgetsPurchased} widgets.");
   */
   

   ब्लॉक टिप्पणियां बहुत अच्छी हैं यदि आपको एक लंबी टिप्पणी लिखने या कोड की कई पंक्तियों को हटाने की आवश्यकता है। ब्लॉक टिप्पणियाँ कोड की शुरुआत में एक /* और अंत में एक */ का उपयोग करें। ब्लॉक टिप्पणी का उपयोग करना कोड की तीन या अधिक पंक्तियों को अक्षम करने का सबसे तेज़ और आसान तरीका है।

9. अपने मौजूदा कोड को निम्न से बदलें:

   Random random = new Random();
   string[] orderIDs = new string[5];
   // Loop through each blank orderID
   for (int i = 0; i < orderIDs.Length; i++)
   {
       // Get a random value that equates to ASCII letters A through E
       int prefixValue = random.Next(65, 70);
       // Convert the random value into a char, then a string
       string prefix = Convert.ToChar(prefixValue).ToString();
       // Create a random number, pad with zeroes
       string suffix = random.Next(1, 1000).ToString("000");
       // Combine the prefix and suffix together, then assign to current OrderID
       orderIDs[i] = prefix + suffix;
   }
   // Print out each orderID
   foreach (var orderID in orderIDs)
   {
       Console.WriteLine(orderID);
   }
   

   नोट

   इस कोड लिस्टिंग में कई सी # अवधारणाएं हैं जो आपके लिए नई हो सकती हैं। यह समझना आवश्यक नहीं है कि कोड क्या कर रहा है ताकि यह सराहना की जा सके कि टिप्पणियां पाठकों को कोड के उद्देश्य को समझने में कैसे मदद कर सकती हैं।

10. यह देखने के लिए एक मिनट का समय लें कि क्या आप कोड के उद्देश्य का पता लगा सकते हैं।

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

11. विचार करें कि आप टिप्पणियों को कैसे सुधारेंगे।

    ध्यान दें कि इन टिप्पणियों के साथ दो मुख्य समस्याएं हैं:

    • कोड टिप्पणियां अनावश्यक रूप से कोड की अलग-अलग लाइनों की स्पष्ट कार्यक्षमता की व्याख्या करती हैं। इन्हें निम्न-गुणवत्ता वाली टिप्पणियाँ माना जाता है क्योंकि वे केवल यह बताते हैं कि C# या .NET क्लास लाइब्रेरी की विधियाँ कैसे काम करती हैं। यदि पाठक इन विचारों से अपरिचित है, तो वे learn.microsoft.com या IntelliSense का उपयोग करके उन्हें देख सकते हैं।
    • कोड टिप्पणियां कोड द्वारा हल की जा रही समस्या का कोई संदर्भ प्रदान नहीं करती हैं। इन्हें निम्न-गुणवत्ता वाली टिप्पणियां माना जाता है क्योंकि पाठक इस कोड के उद्देश्य में कोई अंतर्दृष्टि प्राप्त नहीं करता है, खासकर जब यह बड़ी प्रणाली से संबंधित है।

12. मौजूदा टिप्पणियों को निकालें।

    आपका कोड निम्न से मेल खाना चाहिए:

    Random random = new Random();
    string[] orderIDs = new string[5];
    
    for (int i = 0; i < orderIDs.Length; i++)
    {
        int prefixValue = random.Next(65, 70);
        string prefix = Convert.ToChar(prefixValue).ToString();
        string suffix = random.Next(1, 1000).ToString("000");
    
        orderIDs[i] = prefix + suffix;
    }
    
    foreach (var orderID in orderIDs)
    {
        Console.WriteLine(orderID);
    }
    

    ध्यान दें कि कोड पहले से ही कम अव्यवस्थित है।

13. आपके कोड के उच्च-स्तरीय उद्देश्य की व्याख्या करने वाली टिप्पणी जोड़ने के लिए, निम्नानुसार अपना कोड अपडेट करें:

    /*
      The following code creates five random OrderIDs
      to test the fraud detection process.  OrderIDs 
      consist of a letter from A to E, and a three
      digit number. Ex. A123.
    */
    Random random = new Random();
    string[] orderIDs = new string[5];
    
    for (int i = 0; i < orderIDs.Length; i++)
    {
        int prefixValue = random.Next(65, 70);
        string prefix = Convert.ToChar(prefixValue).ToString();
        string suffix = random.Next(1, 1000).ToString("000");
    
        orderIDs[i] = prefix + suffix;
    }
    
    foreach (var orderID in orderIDs)
    {
        Console.WriteLine(orderID);
    }
    

    एक टिप्पणी की उपयोगिता व्यक्तिपरक है। कोड पठनीयता से संबंधित सभी मामलों में, आपको अपने सर्वोत्तम निर्णय का उपयोग करना चाहिए। वह करें जो आपको लगता है कि आपके कोड की स्पष्टता में सुधार करना सबसे अच्छा है।

संक्षिप्त

इस अभ्यास से मुख्य टेकअवे:

• अपने कोड द्वारा हल की जाने वाली समस्या के बारे में अपने आप को सार्थक नोट्स छोड़ने के लिए कोड टिप्पणियों का उपयोग करें।
• कोड टिप्पणियाँ जो समझाएँ कि कैसे C# या .NET क्लास लायब्रेरी काम करता है का उपयोग न करें।
• वैकल्पिक समाधान आज़माते समय कोड टिप्पणियों का उपयोग तब तक करें जब तक कि आप नए कोड समाधान के लिए प्रतिबद्ध होने के लिए तैयार न हों, जिस बिंदु पर आप पुराने कोड को हटा सकते हैं।
• टिप्पणियों पर कभी भरोसा न करें। वे कई बदलावों और अपडेट के बाद कोड की वर्तमान स्थिति को प्रतिबिंबित नहीं कर सकते हैं।