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

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



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

नामांकन

कोडिंग शैली के मूल नियम नामकरण हैं। नाम की उपस्थिति तुरंत (एक विज्ञापन की खोज के बिना) हमें बताती है कि यह क्या है: प्रकार, चर, कार्य, स्थिर, स्थूल, आदि। नामकरण नियम मनमानी हो सकते हैं, लेकिन स्थिरता महत्वपूर्ण है, और नियमों का पालन किया जाना चाहिए।

सामान्य नामकरण सिद्धांत

• ऐसे नामों का उपयोग करें जो दूसरी टीम के लोग भी समझेंगे।
• नाम वस्तु के उद्देश्य या प्रयोज्यता की बात करना चाहिए।
• नाम की लंबाई पर बचत न करें, बेहतर है कि अधिक लंबा और अधिक समझने योग्य हो (शुरुआती के लिए भी) नाम।
• कम संक्षिप्त रूप से, खासकर यदि वे परियोजना से बाहर अपरिचित हैं।
• केवल ज्ञात संक्षिप्ताक्षर का उपयोग करें (क्या विकिपीडिया उनके बारे में जानता है?)।
• शब्दों को छोटा मत करो।

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

class MyClass { public: int CountFooErrors(const std::vector<Foo>& foos) { int n = 0; //       for (const auto& foo : foos) { ... ++n; } return n; } void DoSomethingImportant() { std::string fqdn = ...; //      } private: const int kMaxAllowedConnections = ...; //     }; 

 class MyClass { public: int CountFooErrors(const std::vector<Foo>& foos) { int total_number_of_foo_errors = 0; //       for (int foo_index = 0; foo_index < foos.size(); ++foo_index) { //   `i` ... ++total_number_of_foo_errors; } return total_number_of_foo_errors; } void DoSomethingImportant() { int cstmr_id = ...; //   ( ) } private: const int kNum = ...; //       }; 

ध्यान दें कि विशिष्ट नाम भी मान्य हैं: मैं एक टेम्पलेट के लिए पुनरावृत्ति या काउंटर, टी के लिए।

भविष्य में, नियमों का वर्णन करते समय "शब्द" / "शब्द" वह सब है जो अंग्रेजी में रिक्त स्थान के बिना लिखा जाता है, जिसमें संक्षिप्तीकरण भी शामिल है। एक शब्द में, पहले अक्षर को कैपिटल किया जा सकता है (शैली के आधार पर: " ऊंट केस " या "पास्कल केस"), शेष अक्षर लोअरकेस हैं। उदाहरण के लिए, अधिमानतः StartRpc () , अधिमानतः StartRPC () ।

टेम्प्लेट पैरामीटर भी उनकी श्रेणियों के नियमों का पालन करते हैं: प्रकार नाम, चर नाम, आदि ...

फ़ाइल नाम

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

उपयुक्त नामों के उदाहरण:

• my_useful_class.cc
• my-useful-class.cc
• myusefulclass.cc
• myusefulclass_test.cc // _unittest और _regtest पदावनत किए जाते हैं।

C ++ फ़ाइलों को .cc में समाप्त होना चाहिए, हेडर में होना चाहिए
.एच । पाठ के रूप में शामिल फ़ाइलों को .inc में समाप्त होना चाहिए (अनुभाग स्वतंत्र हेडर भी देखें)।

उन नामों का उपयोग न करें जो पहले से मौजूद हैं / usr / शामिल हैं , जैसे db.h.

फ़ाइलों को विशिष्ट नाम देने का प्रयास करें। उदाहरण के लिए, http_server_logs.h logs.h से बेहतर है । जब फ़ाइलों का उपयोग जोड़े में किया जाता है, तो उन्हें एक ही नाम देना सबसे अच्छा है। उदाहरण के लिए, foo_bar.h और foo_bar.cc (और वर्ग FooBar शामिल करें)।

नाम टाइप करें

टाइप नाम एक कैपिटल लेटर से शुरू होते हैं, प्रत्येक नया शब्द कैपिटल लेटर से भी शुरू होता है। अंडरस्कोर का उपयोग नहीं किया जाता है: MyExcitingClass , MyExcitingEnum ।

सभी प्रकार के नाम - कक्षाएं, संरचनाएं, उपनाम, गणना, टेम्पलेट पैरामीटर - एक ही शैली में नाम दिए गए हैं। टाइप नाम एक कैपिटल लेटर से शुरू होते हैं, प्रत्येक नया शब्द कैपिटल लेटर से भी शुरू होता है। अंडरस्कोर का उपयोग नहीं किया जाता है। उदाहरण के लिए:

 // classes and structs class UrlTable { ... class UrlTableTester { ... struct UrlTableProperties { ... // typedefs typedef hash_map<UrlTableProperties *, std::string> PropertiesMap; // using aliases using PropertiesMap = hash_map<UrlTableProperties *, std::string>; // enums enum UrlTableErrors { ... 

चर नाम

शब्दों के बीच अंडरस्कोर के साथ वेरिएबल्स (फ़ंक्शन पैरामीटर सहित) और डेटा सदस्यों के नाम निचले अक्षरों में लिखे गए हैं। इन वर्गों के सदस्य (संरचनाएं नहीं) नाम के अंत में एक अंडरस्कोर द्वारा पूरक हैं। उदाहरण के लिए: a_local_variable , a_struct_data_member , a_class_data_member_ ।

सामान्य चर नाम

उदाहरण के लिए:

 std::string table_name; // OK -     

 std::string tableName; //  -   

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

इन वर्गों के सदस्य, स्थिर और गैर-स्थिर, अंत में एक अंडरस्कोर के अतिरिक्त के साथ साधारण चर के रूप में संदर्भित किए जाते हैं।

 class TableInfo { ... private: std::string table_name_; // OK -    static Pool<TableInfo>* pool_; // OK. }; 

संरचना डेटा सदस्य

स्थिर और गैर-स्थैतिक डेटा संरचना के सदस्यों को नियमित चर के रूप में जाना जाता है। अंत में उनके लिए कोई अंडरस्कोर नहीं जोड़ा गया है।

 struct UrlTableProperties { std::string name; int num_entries; static Pool<UrlTableProperties>* pool; }; 

संरचनाएं बनाम कक्षाएं भी देखें, जिसमें बताया गया है कि संरचनाओं का उपयोग कब करना है, कक्षाओं में कब।

स्थिरांक के नाम

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

 const int kDaysInAWeek = 7; const int kAndroid8_0_0 = 24; // Android 8.0.0 

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

फ़ंक्शन नाम

सामान्य कार्यों को एक मिश्रित शैली (अपरकेस और लोअरकेस अक्षर) में नामित किया जाता है; चर एक्सेस फ़ंक्शंस (एक्सेसर और म्यूटेटर) में लक्ष्य चर के समान एक शैली होनी चाहिए।

आमतौर पर, एक फ़ंक्शन नाम कैपिटल अक्षर से शुरू होता है और नाम में प्रत्येक शब्द कैपिटल होता है।

 void AddTableEntry(); void DeleteUrl(); void OpenFileOrDie(); 

(इसी तरह के नियम एक वर्ग या नाम स्थान क्षेत्र में स्थिरांक पर लागू होते हैं जो एपीआई का हिस्सा हैं और उन्हें कार्यों की तरह दिखना चाहिए (और यह तथ्य कि वे कार्य नहीं हैं)

एक्सेसर्स और म्यूटेटर्स (प्राप्त करें और फ़ंक्शन सेट करें) को संबंधित चर की तरह नाम दिया जा सकता है। वे अक्सर वास्तविक सदस्य चर के अनुरूप होते हैं, लेकिन यह आवश्यक नहीं है। उदाहरण के लिए, int count () और void set_count (int count) ।

Namespace Namespace

नेमस्पेस को लोअरकेस कहा जाता है। शीर्ष-स्तरीय नाम स्थान प्रोजेक्ट के नाम पर आधारित है। अपने नाम और अन्य प्रसिद्ध नामस्थानों के टकराव से बचें।

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

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

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

आंतरिक / आंतरिक नामस्थानों के लिए, जब कोई अन्य कोड जोड़ा जाता है, तो टकराव हो सकता है (आंतरिक सहायक विभिन्न टीमों पर दोहराते हैं)। इस स्थिति में, किसी नाम स्थान का नाम रखने के लिए फ़ाइल नाम का उपयोग करने से बहुत मदद मिलती है। ( websearch :: index :: frobber.h में उपयोग के लिए frobber_internal )

गणना नाम

एनुमरेशन्स (दोनों स्कोप्ड अड़चनों के साथ और बिना किसी कारण के) को या तो स्थिरांक या मैक्रो के रूप में जाना जाना चाहिए। वह है: kEnumName या ENUM_NAME ।

प्रगणक में अलग-अलग मूल्यों को स्थिरांक के रूप में नामित करना बेहतर है। हालाँकि, इसे मैक्रोज़ के रूप में संदर्भित करने की अनुमति है। UrlTableErrors (और AlternateUrlTableErrors ) गणन का नाम ही एक प्रकार है। नतीजतन, एक मिश्रित शैली का उपयोग किया जाता है।

 enum UrlTableErrors { kOk = 0, kErrorOutOfMemory, kErrorMalformedInput, }; enum AlternateUrlTableErrors { OK = 0, OUT_OF_MEMORY = 1, MALFORMED_INPUT = 2, }; 

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

मैक्रो के नाम

क्या आप मैक्रोज़ को परिभाषित नहीं कर रहे हैं ? बस के मामले में (यदि आप जा रहे हैं), उन्हें इस तरह दिखना चाहिए:
MY_MACRO_THAT_SCARES_SMALL_CHILDREN_AND_ADULTS_ALIKE ।

कृपया मैक्रो को परिभाषित करने का तरीका पढ़ें; आम तौर पर, मैक्रोज़ का उपयोग नहीं किया जाना चाहिए। हालाँकि, यदि आपको उनकी आवश्यकता है, तो उन्हें बड़े अक्षरों में बड़े अक्षरों में नाम दें।

 #define ROUND(x) ... #define PI_ROUNDED 3.0 

नामकरण अपवाद

यदि आपको किसी ऐसी चीज़ का नाम देना है जिसमें मौजूदा C या C ++ कोड के एनालॉग्स हैं, तो कोड में उपयोग की गई शैली का पालन करें।

bigopen ()
खुले (खुले) नाम से लिया गया फ़ंक्शन नाम

uint
मानक प्रकार के समान परिभाषा

bigpos
पॉज़ से व्युत्पन्न संरचना या वर्ग

sparse_hash_map
एसटीएल जैसी इकाई; एसटीएल शैली का पालन करें

LONGLONG_MAX
INT_MAX की तरह निरंतर

नोट: लिंक मैनुअल के उन वर्गों को ले जा सकते हैं जिन्हें अभी तक अनुवादित नहीं किया गया है।