دليل أنماط Google في C ++. الجزء 8

الجزء 1. مقدمة
...
الجزء 8. التسمية
الجزء 9. التعليقات
...



عند كتابة الكود ، نستخدم جميعًا قواعد تصميم الأكواد. في بعض الأحيان يتم اختراع القواعد الخاصة بهم ، وفي حالات أخرى ، يتم استخدام أدلة النمط الجاهزة. على الرغم من أن جميع مبرمجي C ++ يقرأون باللغة الإنجليزية بشكل أسهل من لغتهم الأم ، إلا أنه من الجيد الحصول على دليل في اللغة الإنجليزية.
هذه المقالة هي ترجمة لجزء من دليل أنماط Google بلغة C ++ إلى الروسية.
المقالة الأصلية (شوكة على جيثب) ، ترجمة محدثة .

ترشيح

القواعد الأساسية لأسلوب الترميز هي تسمية. يخبرنا ظهور الاسم على الفور (دون البحث عن إعلان) ما هو عليه: النوع ، المتغير ، الوظيفة ، الثابت ، الماكرو ، إلخ. يمكن أن تكون قواعد التسمية عشوائية ، ولكن الاتساق مهم ، ويجب اتباع القواعد.

مبادئ التسمية العامة

• استخدم الأسماء التي يفهمها حتى الأشخاص في الفريق الآخر.
• يجب أن يتحدث الاسم عن الغرض أو قابلية التطبيق للتطبيق.
• لا تقم بحفظ طول الاسم ، فمن الأفضل أن يكون لديك اسم أطول وأكثر قابلية للفهم (حتى بالنسبة للمبتدئين).
• اختصارات أقل ، خاصة إذا كانت غير مألوفة خارج المشروع.
• استخدم الاختصارات المعروفة فقط (هل تعرف ويكيبيديا عنها؟).
• لا تقصر الكلمات.

بشكل عام ، يجب أن يتطابق طول الاسم مع حجم النطاق. على سبيل المثال ، 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 = ...; //       }; 

لاحظ أن الأسماء النموذجية صالحة أيضًا: i للمكرر أو العداد ، T لمعلمة القالب.

في المستقبل ، عند وصف القواعد "كلمة" / "كلمة" ، كل ما هو مكتوب باللغة الإنجليزية دون مسافات ، بما في ذلك الاختصارات. باختصار ، يمكن كتابة الأحرف الأولى (حسب النمط: " حالة الجمل " أو "حالة Pascal") ، الأحرف المتبقية صغيرة. على سبيل المثال ، يفضل أن يكون StartRpc () ، ويفضل أن يكون StartRPC () .

تتبع معلمات القوالب أيضًا قواعد فئاتها: أسماء الأنواع ، والأسماء المتغيرة ، إلخ ...

أسماء الملفات

يجب كتابة أسماء الملفات فقط بأحرف صغيرة ، يمكنك استخدام الشرطة السفلية ( _ ) أو الواصلة ( - ) لفصلها. استخدم الفاصل المستخدم في المشروع. إذا لم يكن هناك نهج واحد ، استخدم "_".

أمثلة على الأسماء المناسبة:

• my_useful_class.cc
• my-useful-class.cc
• myusefulclass.cc
• يتم إهمال myusefulclass_test.cc // _unittest و _regtest.

يجب أن تنتهي ملفات C ++ بـ .cc ، ويجب أن يكون الرأس في
ح . يجب أن تنتهي الملفات المدرجة كنص بـ .inc (انظر أيضًا القسم " الرؤوس المستقلة" ).

لا تستخدم أسماء موجودة بالفعل في / usr / include ، مثل 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; }; 

راجع أيضًا الهياكل مقابل الفصول ، التي تصف متى يجب استخدام الهياكل ، متى الفصول.

أسماء الثوابت

يتم تعريف الكائنات على أنها constexpr أو const ، بحيث لا تتغير القيمة أثناء التنفيذ. تبدأ أسماء الثوابت بالرمز "k" ، ثم تأتي الاسم بنمط مختلط (الحروف الكبيرة والصغيرة). يمكن استخدام الشرطة السفلية في حالات نادرة عندما يتعذر استخدام الأحرف الكبيرة للفصل. على سبيل المثال:

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

تتم تسمية جميع الكائنات الثابتة المتشابهة التي لها نوع ثابت من التخزين (أي ثابت أو عام ، لمزيد من التفاصيل هنا: مدة التخزين ). هذا الاصطلاح اختياري للمتغيرات في أنواع التخزين الأخرى (على سبيل المثال ، الكائنات الثابتة التلقائية).

أسماء الوظائف

تتم تسمية الوظائف الشائعة بأسلوب مختلط (أحرف كبيرة وصغيرة) ؛ يجب أن يكون لوظائف الوصول المتغير (accessor و mutator) نمط مماثل للمتغير الهدف.

عادةً ما يبدأ اسم الوظيفة بحرف كبير وكل كلمة في الاسم يتم تكبيرها.

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

(يتم تطبيق قواعد مماثلة على الثوابت في فئة أو مساحة اسم جزءًا من واجهة برمجة التطبيقات ويجب أن تبدو كوظائف (وحقيقة أنها ليست وظائف ليست مهمة).

يمكن تسمية الملحقات والمشغلات (الحصول على وضبط الوظائف) مثل المتغيرات المقابلة. تتوافق غالبًا مع متغيرات الأعضاء الحقيقية ، ولكن هذا ليس ضروريًا. على سبيل المثال ، int count () وباطلة set_count (int count) .

مساحة الاسم

تسمى مساحة الاسم بالأحرف الصغيرة. تعتمد مساحة الاسم ذات المستوى الأعلى على اسم المشروع. تجنب اصطدامات أسماءك ومساحات الأسماء الأخرى المعروفة.

عادةً ما تكون مساحة الاسم ذات المستوى الأعلى هي اسم مشروع أو فريق (مما جعل الكود). يجب أن يكون الكود موجودًا في دليل (أو دليل فرعي) مع اسم مطابق لمساحة الاسم.

لا تنسَ القاعدة بعدم استخدام الاختصارات - وهذا ينطبق أيضًا على مساحات الأسماء. من غير المحتمل أن تتطلب الشفرة الداخلية مرجعًا لمساحة الاسم ، لذا فإن الاختصارات لا لزوم لها.

تجنب استخدام الأسماء المعروفة لمساحات الأسماء المتداخلة. الاصطدامات بين الأسماء يمكن أن تؤدي إلى مفاجآت أثناء التجميع. على وجه الخصوص ، لا تقم بإنشاء مساحات أسماء متداخلة باسم std . يوصى بمعرفات المشروع الفريدة ( websearch :: index ، websearch :: index_util ) بدلاً من عدم الأمان ضد التصادمات websearch :: util .

بالنسبة لمساحات الأسماء الداخلية / الداخلية ، يمكن أن تحدث التصادمات عند إضافة رمز آخر (يميل المساعدون الداخليون إلى تكرار الفرق المختلفة). في هذه الحالة ، فإن استخدام اسم الملف لتسمية مساحة الاسم يساعد كثيرًا. ( websearch :: index :: frobber_internal للاستخدام في frobber.h )

أسماء التعداد

يجب الإشارة إلى التعدادات (سواء مع قيود النطاق وبدون فك التشفير) على أنها إما ثوابت أو وحدات ماكرو . هذا هو: إما 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 ()
اسم الوظيفة مشتق من open ()

UINT
تعريف مماثل للأنواع القياسية

bigpos
هيكل أو فئة مشتقة من نقاط البيع

sparse_hash_map
كيان STL يشبه ؛ اتبع stl الاسلوب

LONGLONG_MAX
ثابت مثل INT_MAX

ملاحظة: قد تؤدي الروابط إلى أقسام من الدليل لم تتم ترجمتها بعد.