C ++ में Google स्टाइल गाइड। भाग 9

भाग 1. परिचय
...
भाग 8. नामकरण
भाग 9. टिप्पणियाँ
...


यह लेख C ++ में Google शैली गाइड के रूसी में अनुवाद का हिस्सा है।
मूल लेख (जीथुब पर कांटा), अद्यतन अनुवाद ।

टिप्पणियाँ

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

अपने निम्नलिखित पाठकों को ध्यान में रखते हुए कोड पर टिप्पणी करें: प्रोग्रामर जिन्हें आपके कोड को समझने की आवश्यकता है। ध्यान रखें कि आप अगले पाठक हो सकते हैं!

टिप्पणी शैली

एकरूपता का उल्लंघन होने तक // या / * * * का उपयोग करें।

आप या तो // या / ** / का उपयोग कर सकते हैं, हालांकि // बहुत बेहतर है। हालाँकि, हमेशा अपनी टिप्पणी शैली को मौजूदा कोड के साथ संरेखित करें।

फ़ाइल हेडर में टिप्पणियाँ

प्रत्येक फ़ाइल के शीर्ष पर एक लाइसेंस हैडर डालें।

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

कानूनी जानकारी और लेखकों की सूची

प्रत्येक फ़ाइल में लाइसेंस की जानकारी होनी चाहिए। विवरण का प्रारूप परियोजना में प्रयुक्त लाइसेंस पर निर्भर करता है। प्रत्येक लाइसेंस (Apache 2.0, BSD, LGPL, GPL, आदि) की अपनी डिजाइन आवश्यकताएं हो सकती हैं।

यदि आप फ़ाइल में महत्वपूर्ण बदलाव करते हैं, तो लेखकों की पिछली सूची को हटाने पर विचार करें। अद्यतित फ़ाइलों में अब कॉपीराइट का उल्लेख और लेखकों की सूची नहीं हो सकती है।

फ़ाइल सामग्री

अगर .ह कई सार की घोषणा करता है, तो फ़ाइल के शीर्षलेख में टिप्पणी को आम तौर पर फ़ाइल की सामग्री और एक दूसरे से संबंधित कैसे सार का वर्णन करना चाहिए। एक टिप्पणी में एक, दो वाक्य आमतौर पर पर्याप्त हैं। अधिक विस्तृत जानकारी कहीं और हस्ताक्षरित है (फ़ाइल के शीर्षलेख में नहीं)।

.H और .cc फ़ाइलों में टिप्पणियों की नकल न करें - टिप्पणियां समय के साथ अलग हो जाती हैं।

कक्षा टिप्पणियाँ

प्रत्येक कक्षा की घोषणा (बहुत स्पष्ट लोगों को छोड़कर) एक टिप्पणी के साथ होनी चाहिए, वर्ग क्या है और इसका उपयोग कैसे करना है।

//   GargantuanTable. // : // GargantuanTableIterator* iter = table->NewIterator(); // for (iter->Seek("foo"); !iter->done(); iter->Next()) { // process(iter->key(), iter->value()); // } // delete iter; class GargantuanTableIterator { ... }; 

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

आप क्लास कमेंट्री में शॉर्ट कोड उदाहरण भी दिखा सकते हैं कि क्लास का उपयोग करना कितना आसान है।

आमतौर पर, एक वर्ग को विभिन्न फाइलों ( .h और .cc ) में घोषित / परिभाषित किया जाता है। वर्ग के उपयोग का वर्णन करने वाली टिप्पणियाँ इंटरफ़ेस की परिभाषा के बगल में होनी चाहिए। कार्यान्वयन की पेचीदगियों पर टिप्पणियाँ स्वयं विधियों के कोड के करीब होनी चाहिए।

टिप्पणियाँ

एक फ़ंक्शन घोषणा पर टिप्पणियाँ फ़ंक्शन के उपयोग का वर्णन करना चाहिए (सबसे स्पष्ट मामलों को छोड़कर)। फ़ंक्शन परिभाषा पर टिप्पणियाँ कार्यान्वयन का वर्णन करती हैं।

समारोह घोषणा

प्रत्येक फ़ंक्शन की घोषणा में एक टिप्पणी होनी चाहिए (घोषणा से ठीक पहले), फ़ंक्शन क्या करता है और इसका उपयोग कैसे करें। एक टिप्पणी को केवल तभी छोड़ा जा सकता है जब फ़ंक्शन सरल हो और उसका उपयोग स्पष्ट हो (उदाहरण के लिए, चर मानों को घटाने का कार्य)। सूचक मूड ("ओपन फ़ाइल") में टिप्पणियां शुरू करने का प्रयास करें। अनिवार्य मनोदशा ("ओपन फाइल") का उपयोग करने की अनुशंसा नहीं की जाती है। एक टिप्पणी एक फ़ंक्शन के सार का वर्णन करती है, न कि यह कैसे करती है।

फ़ंक्शन घोषणा पर टिप्पणी में, निम्नलिखित पर ध्यान दें:

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

एक उदाहरण:

 //    .    //   .    //    GargantuanTable  . // //      . // //    : // Iterator* iter = table->NewIterator(); // iter->Seek(""); // return iter; //         , //    NewIterator()     . Iterator* GetIterator() const; 

हालांकि, स्पष्ट चीजों पर चबाना नहीं है।

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

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

कार्य की परिभाषा

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

ध्यान दें कि आपको फ़ंक्शन की घोषणा पर टिप्पणी को दोहराना नहीं चाहिए (एक .h फ़ाइल या इस तरह से)। यह संक्षेप में वर्णन करना संभव है कि फ़ंक्शन क्या करता है, लेकिन मुख्य बात यह होनी चाहिए कि यह कैसे करता है।

चर पर टिप्पणियाँ

एक अच्छे तरीके से, चर नाम को तुरंत कहना चाहिए कि यह क्या है और क्यों। हालांकि, कुछ मामलों में, अतिरिक्त टिप्पणियों की आवश्यकता होती है।

कक्षा डेटा सदस्य

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

दूसरी ओर, विशेष (और गैर-स्पष्ट) मूल्यों (नल्टर या -1) के विवरण उपयोगी होंगे। उदाहरण के लिए:

 private: //       // -1 - ,         int num_total_entries_; 

वैश्विक चर

सभी वैश्विक चर को उनके उद्देश्य पर टिप्पणी की जानी चाहिए और (यदि स्पष्ट नहीं है) तो उन्हें वैश्विक क्यों होना चाहिए। उदाहरण के लिए:

 //   ,     const int kNumTestCases = 6; 

कार्यान्वयन पर टिप्पणियाँ

कोड के गैर-स्पष्ट, दिलचस्प, महत्वपूर्ण टुकड़ों के मामले में एक फ़ंक्शन या एल्गोरिथ्म के कार्यान्वयन पर टिप्पणी करें।

वर्णनात्मक टिप्पणियाँ

कोड के ब्लॉक जो जटिल या गैर-मानक हैं, उन्हें एक टिप्पणी से पहले होना चाहिए। उदाहरण के लिए:

 //    2.  x    for (int i = 0; i < result->size(); ++i) { x = (x << 8) + (*result)[i]; (*result)[i] = x >> 1; x &= 1; } 

लाइन टिप्पणी

एक टिप्पणी के साथ गैर-स्पष्ट अर्थ के साथ कोड की पंक्तियों को पूरक करने के लिए सलाह दी जाती है (आमतौर पर लाइन के अंत में स्थित)। इस टिप्पणी को कोड से 2 स्थानों से अलग किया जाना चाहिए। उदाहरण के लिए:

 //   ,    mmap_budget = max<int64>(0, mmap_budget - index_->length()); if (mmap_budget >= data_size_ && !MmapData(mmap_chunk_bytes, mlock)) return; //    

ध्यान दें कि कोड ब्लॉक पर 2 टिप्पणियां हैं: एक बताता है कि कोड क्या करता है, दूसरा याद करता है कि फ़ंक्शन से वापसी होने पर त्रुटि पहले से ही लॉग में है।

समारोह तर्क पर टिप्पणियाँ

जब किसी फ़ंक्शन के लिए तर्क निर्दिष्ट करना स्पष्ट नहीं है, तो निम्न विकल्पों पर विचार करें:

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

निम्नलिखित उदाहरणों पर विचार करें:

 //    ? const DecimalNumber product = CalculateProduct(values, 7, false, nullptr); 

कोड को संयोजित करने का प्रयास करते हैं:

 ProductOptions options; options.set_precision_decimals(7); options.set_use_cache(ProductOptions::kDontUseCache); const DecimalNumber product = CalculateProduct(values, options, /*completion_callback=*/nullptr); 

क्या नहीं करना है

स्पष्ट मत करो। विशेष रूप से, उन चीजों की व्याख्या करने की आवश्यकता नहीं है जो सी ++ जानने वाले व्यक्ति के लिए स्पष्ट हैं। इसके बजाय, आप यह बता सकते हैं कि यह कोड ऐसा क्यों करता है (या यहां तक ​​कि कोड को आत्म-वर्णन करना)।

के तुलना करते हैं:

 //    . <-- :  ! auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); } 

इसके साथ:

 //  (Process) "element"     auto iter = std::find(v.begin(), v.end(), element); if (iter != v.end()) { Process(element); } 

स्व-वर्णन कोड को टिप्पणियों की आवश्यकता नहीं है।
उपरोक्त कोड पर टिप्पणी आम तौर पर स्पष्ट हो सकती है (और आवश्यक नहीं):

 if (!IsAlreadyProcessed(element)) { Process(element); } 

विराम चिह्न, वर्तनी और व्याकरण

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

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

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

टिप्पणियाँ TODO

एक अस्थायी कोड या एक अच्छा पर्याप्त (मध्यवर्ती, सही नहीं) समाधान के लिए TODO टिप्पणियों का उपयोग करें।

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

 // TODO(kl@gmail.com):  "*"  . // TODO(Zeke)   . // TODO(bug 12345):   " ". 

यदि आपका TODO "भविष्य में इसे अलग तरीके से करता है" जैसा दिखता है, तो या तो एक विशिष्ट तिथि ("नवंबर 2005 में सही") या एक घटना ("उस कोड को हटाएं जब सभी ग्राहक XML अनुरोधों को संसाधित करेंगे") का संकेत दें।

ध्यान दें।:
- लिंक मैनुअल के उन खंडों को जन्म दे सकते हैं जिनका अभी तक अनुवाद नहीं हुआ है।
- सामान्य मुद्दों की चर्चा सबसे अच्छा भाग 1 में की गई है । परिचय