1.2 — Comments

Comments के प्रकार

Comment texts से बना एक (या ज्यादा) lines का एक sentence है, जिसे codes के बीच में ये समझाने के लिए डाला जाता है, की code आखिर क्या करने के लिए लिखा गया है । C++ में comments दो प्रकार के होते हैं ।

// symbol का प्रयोग एक single-line comment को शुरू करने के लिए किया जाता है, जो compiler को उस line के अंत तक सबकुछ ignore करने की सुचना देता है । उदाहरण के लिए:

1	std::cout << "Hello world!" << endl; // यहाँ से लेकर इस line के अंत तक compiler सबकुछ ignore करेगा

आम तौर पर, single-line comment का इस्तेमाल किसी code line की एक सी छोटी व्याख्या करने के लिए होता है ।

1 2 3

std::cout << "Hello world!" << std::endl; // cout और endl iostream library का हिस्सा हैं std::cout << "It is very nice to meet you!" << std::endl; // ये comments code को पढ़ना मुश्किल बना देते हैं std::cout << "Yeah!" << std::endl; // ज्यादातर उस वक़्त जब lines अलग-अलग लम्बाई की हों

Comments को code line की दायीं ओर रखना comment और code, दोनों को ही पढ़ना मुश्किल बना देता है, विशेषकर जब lines बड़ी हों । इसलिए, // comment को अक्सर code line के ऊपर रखा जाता है ।

1 2 3 4 5 6 7 8

// cout और endl iostream library का हिस्सा हैं std::cout << "Hello world!" << std::endl; // ये आसानी से पढ़ा जा सकता है std::cout << "It is very nice to meet you!" << std::endl; // क्या आपको ऐसा नहीं लगता? std::cout << "Yeah!" << std::endl;

/* और */ symbols के जोड़े का प्रयोग किसी C-style multi-line comment को दर्शाने के लिए किया जाता है । इन दो symbols के बीच आने वाली हर line को compiler ignore कर देता है ।

1 2 3

/* ये एक multi-line comment है    ये सारी lines compiler ignore करेगा    ये वाला भी */

क्यूंकि symbols के बीच का सबकुछ ignore किया जाता है, आप कभी-कभी देखोगे की programmers उनके multi-line comment को “beautify” (देखने में सुन्दर) कर देते हैं:

1 2 3 4

/* ये एक multi-line comment है  * ठीक बायीं ओर एक मिलता-जुलता asterisk  * इसे पढने में आसान बना देता है  */

Multi-line style के comments “एक के भीतर एक” की शैली में नहीं लिखे जा सकते । इसलिए, नीचे दिया गया code अनअपेक्षित result देगा:

1 2	/* ये एक multi-line comment है */ ये line comment के भीतर नहीं है */ // ऊपर दिया गया comment सबसे पहले मिलने वाले */ पर ख़त्म होता है, दुसरे */ पर नहीं

नियम: Comments के भीतर comments कभी ना लिखें

Comments का सही इस्तेमाल

आम तौर पर, comments का इस्तेमाल तीन चीजों के लिए किया जाना चाहिए । किसी library, program, या function level comments का सबसे अच्छा इस्तेमाल वे क्या कर रहे हैं, इसका वर्णन करने के लिए किया जाता है । उदाहरण के लिए:

1	// ये program किसी student के test और homework में प्राप्त अंकों के आधार पर student का final grade calculate करता है ।
1	// ये function किसी समीकरण का अनुमानित root निकालने के लिए newton की विधि का प्रयोग करता है ।

1	// नीचे दी गयी lines किसी चीज़ की दुर्लभता, स्तर और वजन के अनुसार एक यादृच्छिक वस्तु (random item) generate करती है ।

ये सारे comments पढने वालों को program के code को देखे बिना ये जानने में मदद करते हैं की program क्या करने वाला है । User (या कोई और, या फिर आप खुद यदि अपने किसी पुराने code को फिर से इस्तेमाल करना चाह रहे हो तो) comments को देखकर बता सकता है की ये code उसके काम के लिए उपयोगी साबित होगा या नहीं । ये विशेषकर तब महत्वपूर्ण हो जाता है जब किसी team में रहकर काम किया जाता है और सारे लोग लिखे गए सभी codes के बारे में नहीं जानते ।

दूसरा, किसी library, program, function में comments का इस्तेमाल ये बताने के लिए किया जा सकता है की code किस तरह से अपने काम को पूरा करने वाला है ।

1 2 3	/* Final grade calculate करने के लिए, प्राप्त किये गए सभी homework और test scores को जोड़ना होगा, और फिर percentage प्राप्त करने के लिए, इसे सभी scores से भाग देना होगा Percentage का इस्तेमाल बाद में grades calculate करने के लिए किया जायेगा । */
1 2 3 4 5 6	// एक random item generate करने के लिए, हम लोग ये सारी चीजें करने वाले हैं: // 1) वांछित दुर्लभता वाली वस्तुओं (items) को एक list में रखना // 2) वजन और स्तर के अनुसार हर item का एक अनुमान लगाना // 3) एक random number चुनना // 4) पता लगाना की वो number किस item के साथ मेल खाता है // 5) इन सब calculation के बाद सही item प्रदान करना

ये comments code को गहरायी से जाने बगैर पढने वाले को ये बता देते हैं की code किस तरह से अपना काम निपटाने वाला है ।

किसी statement में, comments का इस्तेमाल ये बताने के लिए किया जाना चाहिए की code किसी काम को क्यूँ कर रहा है । एक बुरा statement level comment अकसर code के बारे में ये बताता है की वो क्या करने वाला है । यदि आप कभी ऐसा code लिखोगे जो इतना complex (जटिल) है की code क्या करने वाला है ये बताने के लिए comment की ज़रूरत पड़े, तो आपको इसे थोड़ा आसान बनाकर फिर से लिख लेना चाहिए, ना की इसके काम को समझाने के लिए कोई comment डालना चाहिए ।

नीचे अच्छे और बुरे comments के कुछ उदाहरण दिए गए हैं:

बुरा comment:

1 2	// किसी variable sight को 0 पर set किया जा रहा है sight = 0;

(इसके लिए comment की क्या ज़रूरत है । हमें statement देखकर ही ये पता लग रहा है की यहाँ sight को 0 पर set किया जा रहा है)

अच्छा comment:

1 2	// खिलाडी ने अंधेपन की दवा खा ली है और अब कुछ नहीं देख सकता sight = 0;

(यहाँ हमे पता चल रहा है की आखिर sight को 0 क्यूँ set किया गया है)

बुरा comment:

1 2	// items के दाम calculate कर रहा है cost = items / 2 * storePrice;

(हाँ, हमे statement से पता चल रहा है की यहाँ दाम ही calculate किया जा रहा है, लेकिन item को 2 से भाग क्यों दिया गया है?)

अच्छा comment:

1 2	// हमें items को 2 से भाग देने की ज़रूरत है क्यूंकि वे जोड़ों में ख़रीदे गएँ हैं cost = items / 2 * storePrice;

(अच्छा तो ये बात है!)

Programmers अक्सर किसी problem को solve करने के तरीके का चयन करते हुए भारी परेशानी में पड़ जाते हैं । Comment आपको (या किसी और को) सही solution का चुनाव करते वक़्त लिए गए आपके decision का कारण समझाने का सबसे अच्छा तरीका है ।

अच्छे comments:

1 2	// हमने array की जगह linked list इस्तेमाल किया है क्यूंकि // arrays insertion का काम काफी धीरे करते हैं
1 2	// हमने किसी समीकरण का root (वर्गमूल) पता करने के लिए newton के दिए गये सिद्धांत का प्रयोग किया क्यूंकि // ऐसे समीकरण solve करने का कोई निश्चित तरीका नहीं है

अंत में, comment इस प्रकार से लिखे जाने चाहिए की वे लोग जिन्हें बिलकुल पता नहीं की code क्या करने वाला है, उन्हें भी comments देखकर समझ आने लगे की आखिर code क्या करेगा । अक्सर programmers ऐसा सोचते हैं: “मुझे अच्छी तरह से पता है की ये code क्या करने वाला है! मै इसे कभी नहीं भूलने वाला है और इसलिए यहाँ comments की ज़रूरत नहीं है” अब ज़रा सोचिये यहाँ क्या होगा ? ऐसा ज़रूरी नहीं है, और आपको ये देखकर हैरानी होगी की आप कितनी जल्दी चीजों को भूलते हो । :) आप (या कोई और) खुद को बाद में इस बात के लिए धन्यवाद करोगे की आपने इंसानी भाषा में codes में कैसे, क्या और क्यूँ का जवाब दिया है । code की lines को पढ़कर समझना आसान है । लेकिन वो code वहां किसलिए लिखा गया है, ये समझ पाना मुश्किल ।

याद दिलाने के लिए:

• Library, program, या function level comments “क्या” का जवाब देते हैं ।
• Library, program, या function के भीतर comments “कैसे” का जवाब देते हैं ।
• किसी statement में comments “क्यूँ” का वर्णन करते हैं ।

Code को comment out करना

Code के एक या एक से अधिक lines को comment में बदलना code को comment out करना कहलाता है । ये आपके code के कुछ भागों को शामिल किये बिना program को compile करने (अस्थायी रूप से) का एक सुविधाजनक तरीका है ।

Single line के किसी code को comment out करने के लिए आसानी से code के आगे // का प्रयोग किया जा सकता है:

Uncommented out code:

1	std::cout << 1;

Commented out code:

1	//    std::cout << 1;

Code के एक पूरे भाग को comment out करने के लिए // का प्रयोग एक से अधिक lines में करना चाहिए, या फिर /* */ style comment का प्रयोग करना चाहिए

Uncommented out code:

1 2 3

std::cout << 1;     std::cout << 2;     std::cout << 3;

Commented out code:

1 2 3

//    std::cout << 1; //    std::cout << 2; //    std::cout << 3;

या

1 2 3 4 5

/*     std::cout << 1;     std::cout << 2;     std::cout << 3; */

Codes को comment out करने के कुछ कारण निम्नलिखित हैं:

1) आप अपने program में किसी नए code पर काम कर रहे हो जो अभी compile होने लायक नहीं है, और आपको अचानक program को run करने की ज़रूरत पड़ जाती है । आपका आधा लिखा हुआ code, जिसे आपने कुछ समय पहले लिखना शुरू किया था, वो ज़रूर program को compile करते वक़्त error देगा । तो ऐसे में आप क्या करोगे ? इस code को यदि आप अभी के लिए comment out कर दो, तो compiler उसे ignore कर पूरे program को compile कर लेगा (माना जा रहा है की program में और कोई गलतियाँ नहीं हैं)। जब आप program को compile कर लोगे, तो फिर से उस आधे लिखे code को uncomment कर उसपर काम करना जारी रख सकते हो ।

2) आपने एक ऐसा code लिख दिया है जो compile तो हो जाता है पर अच्छी तरह से काम नही करता, और आपके पास फ़िलहाल इसे fix करने का समय नहीं है । ऐसे में code का वो भाग जिसमे खराबी है, उसे comment out करना ये सुनिश्चित करता है की program का वो भाग execute नहीं होगा, जब तक उसे fix ना कर लिया जाये ।

3) यदि Program का कोई भाग अनअपेक्षित result दे रहा है (अथवा program crash हो जा रहा है) तो code को comment out करना यहाँ भी कारगर साबित होगा । आप program के अलग-अलग parts को comment out कर के program के results देख सकते हो । यदि code में एक या इससे अधिक lines को comment out करने से program ठीक ढंग से काम करने लगता है, तो ज़रूर आपने program के उसी भाग में कोई गलती की है । आप फिर उस जगह पर ज़रा ध्यान देकर ये पता लगा सकते हो की आखिर आपने क्या गलत किया है ।

4) जब आप code के किसी भाग को दुसरे code से बदलना चाहोगे, तो भी comments काम आयेंगे । वास्तविक code को delete किये बिना, आप इसे comment out कर के छोड़ सकते हो जब तक नया code सही ढंग से काम ना करने लगे । जब आपका नया code ठीक से काम करने लगेगा, आप पुराने commented out code को delete कर सकते हो । यदि बहुत कोशिश के बाद भी नया code ठीक तरह काम नहीं कर रहा, तो आप आसानी से नए code को delete कर पुराने code को uncomment कर सकते हो ।

Development के वक़्त codes को comment out करना आम बात है, बहुत सारी IDEs highlighted code को एक ही बार में comment out करने की सुविधा देती है । आप इसका इस्तेमाल कैसे कर सकते हो, ये आपके IDE पर निर्भर करता है (Visual Studio में, आपको Edit menu में इसका option मिलेगा: Edit->Advanced->Comment Selection/Uncomment Selection) ।

इन tutorials में लिखे गए comments पर एक नोट

आगे आने वाले sections में, हमलोग code blocks (ध्यान दें, यहाँ code blocks का मतलब IDE नहीं, code का एक भाग है) । चालाक readers इस बात को नोट करेंगे की ऊपर दिए गए नियमों के मुताबिक, यहाँ के ज्यादातर comments गलत तरीके से लिखे गएँ हैं । :) ध्यान रहे की आगे के tutorials में comments बस चीजों को अच्छी तरह से समझाने के लिए प्रयुक्त हुए हैं, न की ये दिखाने के लिए की अच्छे comments कैसे लिखे जाते हैं ।