دليل جوجل لتنسيق كود جافا

1 المقدمة

يصف هذا المستند معايير الترميز بلغة برمجة Java في Google. يعتبر كود مصدر Java متوافقًا مع هذه المعايير إذا وفقط إذا كان يفي بجميع القواعد الموضحة في هذا المستند.



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

1.1 المصطلحات

في هذا الدليل ، تم تعريف المصطلحات التالية:

1. يستخدم مصطلح الفئة للدلالة على فئة "عادية" أو تعداد أو واجهة أو نوع تعليق توضيحي (interface)
2. يتم استخدام مصطلح عضو الفئة للإشارة إلى فئة أو حقل أو طريقة أو مُنشئ متداخل ، أي لجميع أعضاء الفئة عالية المستوى باستثناء كتل التهيئة والتعليقات
3. يشير مصطلح التعليق دائمًا إلى تعليقات التنفيذ. نحن لا نستخدم عبارة "تعليقات التوثيق" ، ولكن بدلاً من ذلك نستخدم مصطلح "Javadoc"

سيتم توفير بقية المصطلحات حسب الحاجة في هذا الدليل.

1.2 مذكرة إرشادية

لا توضح أمثلة الكود في هذا المستند الأسلوب الأسلوب الصحيح الوحيد لتنسيقه ، على الرغم من استخدامها في برنامجنا التعليمي.

2. ملف المصدر. أساسيات

2.1 اسم الملف

يتكون اسم الملف المصدر من اسم فئة المستوى الأعلى المحددة الموجودة فيه. الاسم حساس لحالة الأحرف وينتهي بملحق .java

2.2 ترميز الملف: UTF-8

يتم ترميز الملفات ذات التعليمات البرمجية بتنسيق UTF-8.

2.3 أحرف خاصة

2.3.1 أحرف المسافة

بصرف النظر عن تسلسل الأحرف في نهاية السطر ، فإن حرف مسافة ASCII الأفقي (0x20) هو الحرف المحدد الوحيد الموجود في الملف المصدر. هذا يعني انه:

1. يتم تخطي جميع أحرف المسافات البيضاء الأخرى في الأحرف والسلسلة الحرفية
2. لا يتم استخدام أحرف الجدولة للمسافة البادئة

2.3.2 تسلسلات الهروب الخاصة

لكل حرف يوجد له تسلسل هروب خاص (\ b ، \ t ، \ n ، \ f ، \ r ، \ "، \ 'و \\) ، يفضل استخدامه بدلاً من قيمته الثمانية المقابلة (على سبيل المثال ، \ 012 ) أو رمز Unicode (مثل \ u000a).

2.3.3 أحرف غير ASCII

بالنسبة للأحرف غير ASCII ، استخدم حرف Unicode (على سبيل المثال ، ∞) أو ​​تسلسل هروب مكافئ (على سبيل المثال ، \ u221e). يتم الاختيار لصالح تلك الرموز التي تجعل الكود أكثر قابلية للفهم والقراءة.

عند استخدام أحرف الهروب في ترميز Unicode وفي الحالات التي يتم فيها استخدام أحرف Unicode صالحة ، نوصي بشدة أن يكون هذا الرمز مصحوبًا بتعليقات توضيحية.

لا تجعل الكود الخاص بك أقل قابلية للقراءة لمجرد الخوف من أن بعض البرامج لن تكون قادرة على معالجة الأحرف غير ASCII بشكل صحيح. إذا حدث هذا ، فإن هذه البرامج لا تعمل بشكل صحيح وتحتاج إلى الإصلاح.

3. هيكل ملف المصدر

يتكون الملف المصدر من العناصر التالية (بالترتيب الموضح):

1. معلومات الترخيص أو حقوق النشر ، إن وجدت
2. إعلان الحزمة
3. التصريح عن الواردات
4. إعلان الفئة

يفصل سطر فارغ واحد بالضبط كل قسم موجود.

3.1 معلومات الترخيص أو حقوق النشر ، إن وجدت

يجب تضمين معلومات الترخيص أو حقوق النشر في الملف الذي تشير إليه.

3.2 إعلان الحزمة

تم التصريح عن الحزمة بدون فاصل سطر. لا ينطبق تحديد عرض الخط (القسم 4.4) على إعلان الحزمة.

3.3 إقرارات الاستيراد

3.3.1 حرف البدل في إقرارات الاستيراد

لا يتم استخدام الحرف * (wildcard) عند الإعلان عن عمليات الاستيراد ، سواء أكانت ثابتة أم لا.

3.3.2 فاصل الأسطر

يتم الإعلان عن الواردات بدون فواصل أسطر. لا تخضع لحد عرض الخط.

3.3.3 الترتيب والتباعد

يتم ترتيب الواردات على النحو التالي:

1. يتم وضع كافة عمليات الاستيراد الثابتة وتجميعها في كتلة واحدة
2. يتم وضع كافة عمليات الاستيراد غير الثابتة في كتلة أخرى

إذا تم التصريح عن كلٍ من عمليات الاستيراد الثابتة وغير الثابتة ، فيجب فصل هذه الكتل بسطر فارغ. يجب ألا يكون هناك أي أسطر فارغة أخرى بينهما.



داخل كل كتلة ، يتم إدراج الفئات المستوردة بترتيب فرز أحرف ASCII.

3.3.4 استيراد ثابت للفئات المتداخلة

لا يتم استخدام الواردات الثابتة للفئات المتداخلة الثابتة. يتم استيراد هذه الفئات مع بيان استيراد عادي.

3.4 إعلان الفئة

3.4.1 تم الإعلان عن فئة واحدة فقط من المستوى الأعلى

توجد كل فئة من المستوى الأعلى في ملف المصدر الخاص بها.

3.4.2 ترتيب محتويات الفصل

يمكن أن يكون للترتيب الذي تضع به الأعضاء وكتل التهيئة للفصل تأثير كبير على مدى سهولة فهم الكود الخاص بك. في كلتا الحالتين ، لا توجد وصفة بسيطة وصحيحة لذلك ؛ يمكن للفئات المختلفة ترتيب محتواها بشكل مختلف.



الشيء المهم هو أن لكل فئة ترتيب منطقي للمحتوى حتى يتمكن المبرمج الذي يقرأ الكود من شرحه.

2.1.4.3 يجب عدم تجزئة الشفرة المحملة بشكل زائد

عندما يكون للفصل عدة منشئات أو طرق بنفس الاسم ، يجب وضعها بالتسلسل دون إدخال رمز آخر بينهما.

4. التنسيق

المصطلح

جسم الفئة أو الطريقة أو المُنشئ هو بناء كتلة .



لاحظ أنه وفقًا للقسم 4.8.3.1 ، يمكن أيضًا اعتبار أي مُهيئ للصفيف بناء كتلة.

4.1 الأقواس المجعدة

4.1.1 يتم استخدام الأقواس المتعرجة أينما يمكن استخدامها

يتم استخدام الأقواس المتعرجة في if ، و else ، و while ، و do-while ، حتى إذا كان جسم التعبير فارغًا أو يحتوي على سطر واحد فقط من التعليمات البرمجية.

4.1.2 الكتل غير الفارغة: نمط K&R

يتم وضع الأقواس المتعرجة وفقًا لأسلوب Kernighan و Ritchie ("الأقواس المصرية") للكتل غير الفارغة وهياكل الكتل (للتوضيح ، قررنا إضافة رمز صغير يوضح هذه القواعد - ملاحظة المترجم):

• لا يتم إجراء فاصل أسطر قبل فتح قوس:

// 
if (true) { 

// 
if (true)
{

• يتم إجراء فاصل أسطر بعد قوس الفتح:

// 
while (true) {
  // code

// 
while (true) { // code

• يتم إجراء فاصل أسطر قبل قوس الإغلاق:

// 
for () {
  // code
}

// 
while (true) { /* code */ }

// 
if (true) {
  /* code */ }

• يحدث فاصل الأسطر بعد قوس إغلاق فقط إذا أنهى هذا القوس تعبيرًا أو نصًا لطريقة أو مُنشئ أو فئة غير مجهولة. لا يتم فاصل الأسطر بعد قوس إذا تبعه آخر ، التقاط أو فاصلة منقوطة

أمثلة على القواعد التي تم تنفيذها بشكل صحيح:

return () -> {
  while (condition()) {
    method();
  }
};

return new MyClass() {
  @Override public void method() {
    if (condition()) {
      try {
        something();
      } catch (ProblemException e) {
        recover();
      }
    } else if (otherCondition()) {
      somethingElse();
    } else {
      lastThing();
    }
  }
};

ترد بعض الاستثناءات من التعدادات في القسم 4.8.1

4.1.3 يمكن ضغط الكتل الفارغة

يمكن أن يتبع بناء الكتلة الفارغة أو الكتلة الفارغة نمط K & R (كما هو موضح في القسم 4.1.2). من الممكن أيضًا إغلاق مثل هذه الكتلة فور فتحها ، بدون أحرف أو فواصل أسطر داخل {}. لا تنطبق هذه القاعدة عندما تكون الكتلة جزءًا من تعبير متعدد الكتل يحتوي على if-else أو try-catch-finally.



أمثلة:

// 
void doNothing() {}

//  
void doNothingElse() {
}

// :       
try {
  doSomething();
} catch (Exception e) {}

4.2 مسافتان للمسافة البادئة

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

4.3 تعبير واحد في كل سطر

ينتهي كل تعبير بفاصل أسطر.

4.4 تحديد عرض الخط بـ 100 حرف

كود Java يقتصر على 100 حرف في عرض الخط. يشير "الحرف" إلى أي عنصر من عناصر Unicode. باستثناء ما هو موضح أدناه ، يجب تغليف كل سطر يتجاوز حد العرض كما هو موضح في القسم 4.5.



استثناءات:

1. , (, URL Javadoc JSNI- )
2. package import (. 3.2 3.3)
3. ,

4.5

عندما يتم تقسيم الكود الذي قد يكون على نفس السطر عبر عدة أسطر ، فإن هذه الظاهرة تسمى فاصل الأسطر.



لا توجد صيغة مقبولة بشكل عام لا لبس فيها تحدد بالضبط كيفية عمل فواصل الأسطر في كل موقف. غالبًا ما توجد عدة طرق لكسر السطر بنفس جزء الكود.



عادة ما يتم الالتفاف لتجنب تجاوز عرض الخط. ولكن حتى إذا ظل الرمز ضمن العرض المسموح به ، فبإمكان المؤلف ، بناءً على قرار المؤلف ، تغليفه بسطر جديد.

يمكن أن يؤدي تخصيص طريقة مساعدة أو متغير محلي إلى حل مشكلة تجاوز عرض الخط دون التفاف الكود

4.5.1 مكان التحويل

المبدأ التوجيهي الأول لفواصل الأسطر يقول: من الأفضل القيام بفاصل الأسطر عند مستوى نحوي أعلى. أيضًا:



1. عند كسر سطر في عبارة عدم تخصيص ، يتم إجراء الفاصل قبل الحرف.



تنطبق هذه القاعدة أيضًا على الأحرف "المشابهة لعامل التشغيل" التالية:

• نقطة الانقسام "."
• نقطتان مزدوجتان للطريقة المرجعية "::"
• علامة العطف بين قوسين عام <T يمتد Foo & Bar>
• المحدد في كتلة catch (FooException | BarException e)

2. عندما يتم لف سلسلة في جملة مهمة ، عادة ما يتم الالتفاف بعد الحرف ، لكن هناك حل آخر مقبول ،



وهذا ينطبق أيضًا على النقطتين لكل حلقة.



3. اسم الطريقة أو المُنشئ عند فواصل الأسطر يظل مرتبطًا بقوس الفتح "("



4. الفاصلة "،" عندما يظل السطر مع العنصر الذي يسبقه



5. لا يتم لف السطر مباشرةً في سهم تعبير لامدا ، ما لم يتكون جسمه من تعبير واحد بدون أقواس مجعدة:

MyLambda<String, Long, Object> lambda =
    (String label, Long value, Object obj) -> {
        ...
    };

Predicate<String> predicate = str ->
    longExpressionInvolving(str);

الغرض الرئيسي من فواصل الأسطر هو تحقيق الوضوح في الكود ، ولكن ليس بالضرورة أصغر عدد من الأسطر

4.5.2 متابعة خط الإزاحة بمقدار 4 مسافات أو أكثر

عندما ينكسر سطر ، يتم إزاحة كل سلسلة فرعية لاحقة (كل سطر تابع) بمقدار 4 مسافات على الأقل بالنسبة إلى السابقة.



عندما يكون هناك عدة خطوط متصلة ، يمكن أن تختلف الإزاحة في 4 مسافات بناءً على طلب المؤلف. كقاعدة عامة ، يمكن أن يكون لامتداد خطين نفس الإزاحة إذا وفقط إذا بدأوا بعناصر توازية نحوية.



يوفر القسم 4.6.3 إرشادات حول استخدام كميات متباينة من المساحات البيضاء لمحاذاة نقاط الرمز بالنسبة للأسطر السابقة.

4.6 المسافات والمسافات البادئة

4.6.1 المسافة البادئة

يتم وضع سطر واحد فارغ دائمًا:



1. بين الأعضاء المتتاليين أو مُهيئ الفئة: الحقول والمنشئات والأساليب والفئات المتداخلة وكتل التهيئة الثابتة والديناميكية

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

2. بما يتفق مع الأقسام الأخرى من هذه الوثيقة (مثل القسم 3 والقسم 3.3)



يمكن أيضًا استخدام السطر الفارغ في كل مكان لتحسين قابلية قراءة الكود ، على سبيل المثال بين التعبيرات لتنظيم الكود في أقسام فرعية منطقية. سلسلة فارغة قبل أول عضو في الفئة ، أو كتلة التهيئة ، أو بعد العضو الأخير ، أو كتلة التهيئة للفئة غير مستحبة ، ولكن ليس ممنوعًا.



يُسمح باستخدام أسطر فارغة متعددة متتالية ، ولكن ليس ضروريًا أو مشجعًا.

4.6.2 المسافات

بصرف النظر عن متطلبات اللغة نفسها أو القواعد الأخرى لهذا المستند ، بالإضافة إلى عدم احتساب الحروف والتعليقات (بما في ذلك Javadoc) ، يمكن أن تظهر المسافات المفردة من جدول ASCII فقط في الأماكن التالية:



1. عند فصل أي كلمة محجوزة مثل if ، for or catch وقوس فتح "(" الذي يلي



2. عند فصل أي كلمة محجوزة ، مثل else أو catch ، وقوس إغلاق متعرج "}" يلي



3. قبل أي قوس فتح متعرج " {"، باستثناء حالتين:

• SomeAnnotation ({a، b})
• سلسلة [] [] x = {{"foo"}} ؛ - مسافة بين {{غير مطلوبة وفقًا للفقرة 8 أدناه

4. على جانبي أي عامل تشغيل ثنائي أو ثلاثي



تنطبق هذه القاعدة أيضًا على عوامل التشغيل التالية:

• قوس العطف الداخلي بين قوسين: <T يمتد Foo & Bar>
• محدد في كتلة catch تحتوي على استثناءات متعددة: catch (FooException | BarException e)
• القولون ":" في مقابل كل
• السهم في تعبير لامدا: (سلسلة سلسلة) -> str.length ()

لكن هذه القاعدة لا تنطبق على المشغلين:

• نقطتان مزدوجتان "::" للطريقة المرجعية ، والتي تتم كتابتها كـ Object :: toString
• النقطة الفاصلة "." ، والتي تتم كتابتها على هيئة object.toString ()

5. بعد "،: ؛" أو قوس الإغلاق ")" عند الإرسال إلى النوع



6. على جانبي الشرطة المائلة المزدوجة للأمام "//" عند إنشاء تعليق على نفس سطر التعليمات البرمجية. يُسمح بالمسافات المتعددة ولكنها غير مطلوبة هنا



7. بين تعريف النوع واسم المتغير:

List<String> list

8. اختياري: داخل أقواس مُهيئ المصفوفة

new int [] {5، 6} و new int [] {5، 6} كلاهما صالح



9. بين التعليق التوضيحي للنوع و [] أو ...



هذه القاعدة لا تتطلب وجود أو عدم وجود مسافات في بداية أو نهاية السطر ؛ ينطبق فقط على المساحات الداخلية.

4.6.3 المحاذاة الأفقية غير مطلوبة أبدًا

المصطلح

المحاذاة الأفقية هي ممارسة إضافة عدد متغير من المسافات الإضافية في التعليمات البرمجية الخاصة بك لجعل بعض العناصر تظهر أسفل عناصر أخرى من السطر السابق.



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



مثال مع وبدون محاذاة:

private int x; // 
private Color color; //   

private int   x;      // ,     
private Color color;  //    

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

4.7 يوصى باستخدام أقواس التجميع

يجب ألا تحذف أقواس التجميع إلا إذا اتفق مؤلف الكود والمراجع على أنه لا يوجد احتمال معقول بأن يتم تفسير الكود بشكل خاطئ بدون أقواس ، كما أن الأقواس لن تسهل قراءتها. لا يوجد سبب للاعتقاد بأن أي شخص يقرأ الكود قد حفظ جدول أسبقية مشغل Java بالكامل.

4.8 تصميمات خاصة

4.8.1 فئات العد

يعد فاصل الأسطر اختياريًا بعد كل فاصلة تتبع ثابت التعداد. يُسمح أيضًا بخطوط فارغة إضافية (عادةً سطر واحد فقط). إليك مثال على هذا الرمز:

private enum Answer {
  YES {
    @Override public String toString() {
      return "yes";
    }
  },

  NO,
  MAYBE
}

يمكن تمثيل كود فئة التعداد بدون طرق وتعليقات تصف ثوابتهم كمبدئ للصفيف (انظر القسم 4.8.3.1):

private enum Suit { CLUBS, HEARTS, SPADES, DIAMONDS }

نظرًا لأن التعدادات عبارة عن فئات ، فيجب أن تنطبق عليها جميع القواعد الأخرى التي تنطبق على الفئات.

4.8.2 الإعلانات المتغيرة

4.8.2.1 متغير واحد لكل تصريح

يتم التصريح عن كل متغير (حقل أو محلي) واحدًا فقط في كل مرة: تصريحات مثل int a، b؛ لا تستخدم.



استثناء : يُسمح بإعلانات المتغيرات المتعددة في رأس حلقة for.

4.8.2.2 قم بتعريف المتغيرات عندما تحتاج إليها

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

4.8.3 المصفوفات

4.8.3.1 يمكن أن تكون مُهيئات الصفيف "block"

يمكن تهيئة أي مصفوفة كما لو كانت بناء كتلة. على سبيل المثال ، كل التعليمات البرمجية التالية صالحة (قائمة الأمثلة ليست كاملة):

new int[] {
  0, 1, 2, 3
}
                        
new int[] {
  0, 1,
  2, 3
}

new int[]
    {0, 1, 2, 3}

new int[] {
  0,
  1,
  2,
  3
}

4.8.3.2 لا توجد إعلانات مصفوفة من النمط C.

توضع الأقواس المربعة بعد النوع ، وليس بعد المتغير: String [] args ، وليس String args [].

4.8.4 بيان التبديل

المصطلح

توجد مجموعة واحدة أو أكثر من العبارات داخل كتلة تبديل. تتكون كل مجموعة من تصنيف واحد أو أكثر (كلتا الحالتين FOO: والافتراضي :) متبوعًا بعبارة واحدة أو أكثر (أو في حالة المجموعة الأخيرة ، لا شيء أو أكثر).

4.8.4.1 الإزاحة

كما هو الحال مع أي كتلة أخرى ، يتم تعويض محتويات كتلة التبديل بمسافتين.



يتم إجراء فاصل أسطر بعد تسمية كتلة المفتاح ، ويتم زيادة الإزاحة بمسافتين ، تمامًا كما حدث عند فتح الكتلة. تعود كل تسمية تالية إلى مستوى الإزاحة السابق ، كما هو الحال عند إغلاق كتلة.

4.8.4.2 تم التعليق على الممر

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

switch (input) {
  case 1:
  case 2:
    prepareOneOrTwo();
    // fall through
  case 3:
    handleOneTwoOrThree();
    break;
  default:
    handleLargeNumber(input);
}

يرجى ملاحظة أن التعليق لا يتم وضعه بعد الحالة 1 ، ولكن فقط في نهاية مجموعة البيانات.

4.8.4.3 استخدم الافتراضي دائمًا

يجب أن تحتوي عبارة التبديل على التسمية الافتراضية ، حتى إذا لم يكن بها رمز.



استثناء : قد لا تستخدم كتلة التبديل الخاصة بنوع التعداد الافتراضي إذا كانت تحتوي على حالات صريحة تغطي جميع القيم المحتملة لهذا النوع. يتيح ذلك لـ IDE أو أدوات التحليل الثابتة الأخرى إصدار تحذير بعدم تغطية بعض الحالات.

4.8.5 التعليقات التوضيحية

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

@Override
@Nullable
public String getNameIfPresent() { ... }

استثناء : يمكن عرض تعليق توضيحي واحد بدون معلمات مع سطر التوقيع الأول ، على سبيل المثال:

@Override public int hashCode() { ... }

تظهر التعليقات التوضيحية المطبقة على أحد الحقول أيضًا مباشرةً بعد كتلة المستند ، ولكن في هذه الحالة يمكن إدراج العديد من التعليقات التوضيحية (ربما تكون ذات معلمات) في سطر واحد ، على سبيل المثال:

@Partial @Mock DataLoader loader;

لا توجد قواعد خاصة لتنسيق التعليقات التوضيحية للمعلمات أو المتغيرات المحلية أو الأنواع.

4.8.6 التعليقات

هذا القسم مخصص لتعليقات التنفيذ. تمت مناقشة Javadoc بشكل منفصل في القسم 7.



أي فاصل سطر يمكن أن يسبقه عدد عشوائي من المسافات ، متبوعًا بتعليق تنفيذي. هذا التعليق يجعل السطر غير فارغ.

4.8.6.1 حظر نمط التعليق

مستوى المسافة البادئة لتعليق الكتلة هو نفس الكود المحيط. يمكن أن تكون التعليقات المحظورة إما / * ... * / أو // ... للتعليقات متعددة الأسطر مثل / * ... * / ، يجب أن تبدأ الأسطر التالية بـ * ، محاذاة مع * من السطر السابق.

/*
 * This is          // And so           /* Or you can
 * okay.            // is this.          * even do this. */
 */

لم يتم تضمين التعليقات في مستطيلات ممثلة بعلامات نجمية أو رموز أخرى.

عند كتابة تعليقات متعددة الأسطر ، استخدم النمط / * ... * / إذا كنت تريد من مُنسق التعليمات البرمجية التلقائي كسر السطر حسب الحاجة (نمط الفقرة). لا يمكن لمعظم المنسقين القيام بذلك باستخدام كتل تعليق سطر واحد // ...

4.8.7 المعدلات

يتم عرض مُعدِّلات الفئات والحقول ، إن وجدت ، بالترتيب الموصى به في مواصفات لغة Java:

public protected private abstract default static final transient volatile synchronized native strictfp

4.8.8 القيم الحرفية الرقمية

يستخدم النوع الطويل حرف L كبير ، وليس حرفًا صغيرًا (حتى لا يتم الخلط بينه وبين الرقم 1). على سبيل المثال ، 300_000_000 لتر بدلاً من 300_000_000 لتر.

5. التسمية

5.1 قواعد عامة لجميع المعرفات

تستخدم المعرفات أحرف وأرقام ASCII فقط ، وفي بعض الحالات المذكورة أدناه ، خطوط سفلية.



وبالتالي ، تتم مطابقة كل اسم معرف صالح بالتعبير العادي \ w + (حرف أبجدي رقمي يظهر مرة واحدة أو أكثر).



الأسماء التي تستخدم لاحقات أو بادئات خاصة ، مثل name_ أو mName أو s_name أو kName ، لا تتوافق مع نمط هذا البرنامج التعليمي.

5.2 قواعد لأنواع مختلفة من المعرفات

5.2.1 أسماء الحزم

يجب كتابة أسماء الحزم بأحرف صغيرة ، بدون أحرف الجمل أو الشرطة السفلية.



صحيح: com.example.deepspace

غير صحيح: com.example.deepSpace أو com.example.deep_space

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

تتم كتابة أسماء الفئات بأسلوب UpperCamelCase (الحرف الأول بحرف كبير).



عادة ما تكون أسماء الفئات عبارة عن أسماء أو عبارات اسمية. على سبيل المثال ، شخصية أو قائمة غير قابلة للتغيير.



يمكن أن تكون أسماء الواجهات أيضًا أسماء أو عبارات اسمية (على سبيل المثال ، قائمة) ، ولكن في بعض الأحيان يمكن أن تكون أيضًا صفات أو مجموعات صفية (على سبيل المثال ، مقروءة).



لا توجد قواعد محددة أو حتى اصطلاحات راسخة لتسمية أنواع التعليقات التوضيحية.



فصول الاختبار لها اسم يبدأ باسم الفصل الذي يختبرونه وينتهي بكلمة اختبار. على سبيل المثال ، HashTest أو HashIntegrationTest.

5.2.3 أسماء الطرق

تتم كتابة أسماء الطرق بأسلوب LowerCamelCase.



عادةً ما تكون أسماء الطرق عبارة عن أفعال أو عبارات فعل. على سبيل المثال sendMessage أو stop.



يمكن استخدام الخطوط السفلية في أسماء طرق اختبار JUnit لفصل المكونات المنطقية في الاسم. علاوة على ذلك ، تتم كتابة كل مكون في نمط LowerCamelCase. النمط النموذجي هو:

<methodUnderTest>_<state>, , pop_emptyStack

لا توجد طريقة واحدة صحيحة لتسمية طرق الاختبار.

5.2.4 الأسماء الثابتة

تتم تسمية الثوابت في نمط CONSTANT_CASE: جميع الأحرف كبيرة ، ويتم فصل كل كلمة عن التالية بشرطة سفلية. لكن ما هو بالضبط الثابت؟



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



أمثلة:

// 
static final int NUMBER = 5;
static final ImmutableList<String> NAMES = ImmutableList.of("Ed", "Ann");
static final ImmutableMap<String, Integer> AGES = ImmutableMap.of("Ed", 35, "Ann", 32);
static final Joiner COMMA_JOINER = Joiner.on(','); // because Joiner is immutable
static final SomeMutableType[] EMPTY_ARRAY = {};
enum SomeEnum { ENUM_CONSTANT }

//  
static String nonFinal = "non-final";
final String nonStatic = "non-static";
static final Set<String> mutableCollection = new HashSet<String>();
static final ImmutableSet<SomeMutableType> mutableElements = ImmutableSet.of(mutable);
static final ImmutableMap<String, SomeMutableType> mutableValues =
    ImmutableMap.of("Ed", mutableInstance, "Ann", mutableInstance2);
static final Logger logger = Logger.getLogger(MyClass.getName());
static final String[] nonEmptyArray = {"these", "can", "change"};

عادةً ما تكون الأسماء الثابتة عبارة عن أسماء أو عبارات اسمية.

5.2.5 أسماء الحقول غير الثابتة

تتم كتابة أسماء الحقول التي ليست ثوابت (ثابتة أو غير ثابتة) في نمط LowerCamelCase.



عادة ما تكون أسماء هذه الحقول عبارة عن أسماء أو عبارات اسمية. على سبيل المثال ، القيم المحسوبة أو الفهرس.

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

تتم كتابة أسماء المعامِلات بأسلوب LowerCamelCase.



يجب تجنب أسماء المعلمات المكونة من حرف واحد في الطرق العامة.

5.2.7 أسماء المتغيرات المحلية

تتم كتابة أسماء المتغيرات المحلية في نمط LowerCamelCase.



على الرغم من أنها نهائية وغير قابلة للتغيير ، لا تعتبر المتغيرات المحلية ثوابت ولا يجب كتابتها بنفس أسلوب الثوابت.

5.2.8 أسماء متغيرات النوع

يتم تسمية كل متغير نوع وفقًا لأحد النمطين:

• حرف واحد كبير يمكن أن يتبعه رقم عادي (على سبيل المثال ، E ، T ، X ، T2)
• اسم على شكل اسم فئة (انظر القسم 5.2.2) متبوعًا بحرف كبير T (أمثلة: RequestT ، FooBarT).

5.3 نمط الجمل (علبة الجمل)

في بعض الأحيان ، توجد أكثر من طريقة لتحويل عبارة إنجليزية إلى نمط جمل ، كما هو الحال في حالة الاختصارات أو التعبيرات غير النمطية مثل "IPv6" أو "iOS".



لزيادة القدرة على التنبؤ ، يحدد هذا الدليل المخطط (النموذجي) التالي.



بدءًا من الشكل الأصلي للاسم:



1. قم بتحويل العبارة إلى ASCII عادي وقم بإزالة جميع الفواصل العليا. على سبيل المثال ، يمكن تحويل "خوارزمية مولر" إلى "خوارزمية مولر"



2. قسّم النتيجة إلى كلمات ، وتجاهل المسافات وعلامات الترقيم المتبقية (عادةً ما تكون واصلات):

• التوصية: إذا كانت أي كلمة لها شكل شائع بالفعل في نمط "الجمل" المعتاد ، فقسِّمها إلى الأجزاء المكونة لها (على سبيل المثال ، يتم تحويل "AdWords" إلى "كلمات إعلانية"). لاحظ أن كلمة مثل "iOS" ليست في الحقيقة على غرار الجمل. لا تمتثل لأية اتفاقيات ، لذلك لا تنطبق هذه التوصية.

3. الآن قم بتحويل كل شيء إلى أحرف صغيرة (بما في ذلك الاختصارات) ، ثم قم بتحويل الحرف الأول إلى الأحرف الكبيرة:

• ... في كل كلمة لتحقيق أسلوب UpperCamelCase ، أو
• ... في كل كلمة باستثناء أول من يحقق أسلوب حالة الجمل المنخفضة

4. أخيرًا ، قم بتجميع كل الكلمات في معرف واحد ،



ولاحظ أن حالة الكلمات الأصلية يتم تجاهلها بالكامل تقريبًا.



أمثلة:



* مسموح به ولكن غير موصى به.



ملحوظة : بعض الكلمات في اللغة الإنجليزية تستخدم الواصلة بشكل غامض: على سبيل المثال ، كل من "غير فارغ" و "غير فارغ" صحيحان ، لذا فإن أسماء الطرق checkNempty و checkNonEmpty صحيحة أيضًا.

6. ممارسة البرمجة

6.1 استخدم دائمًا التعليق التوضيحيOverride

يتم وضع تعليقات توضيحية على الطريقة باستخدام التعليق التوضيحيOverride عندما يتم تجاوزها بالفعل. ينطبق هذا على كل من طريقة الفئة الفرعية التي تتجاوز طريقة الفئة الأصلية ، وطريقة الواجهة التي تتجاوز طريقة الواجهة الفائقة.



استثناء : يمكن حذف التعليق التوضيحي إذا تم تمييز الطريقة الأصلية بتعليقDeprecated.

6.2 لا تتجاهل الاستثناءات التي تم التقاطها

من النادر جدًا وجود مواقف لا تحتاج فيها إلى اتخاذ أي إجراء ردًا على استثناء تم اكتشافه (الحل النموذجي هو تسجيله أو ، إذا تم اعتباره "مستحيلًا" ، طرح الاستثناء كخطأ AssertionError).



يوجد أدناه مثال مع تعليق توضيحي حول متى يكون من المناسب حقًا عدم اتخاذ أي إجراء في كتلة catch:

try {
  int i = Integer.parseInt(response);
  return handleNumericResponse(i);
} catch (NumberFormatException ok) {
  // it's not numeric; that's fine, just continue
}
return handleTextResponse(response);

استثناء : في الاختبارات ، قد يتم تجاهل الاستثناء الذي تم اكتشافه وإلغاء التعليق عليه إذا كان اسم الاختبار متوقعًا أو إذا كان الاسم يبدأ بـ متوقع. ما يلي هو مصطلح شائع جدًا يوضح أن الكود قيد الاختبار يطرح استثناءً من النوع المتوقع ، لذلك لا توجد تعليقات مطلوبة هنا:

try {
  emptyStack.pop();
  fail();
} catch (NoSuchElementException expected) {
}

6.3 للأعضاء الساكنين ، استخدم اسم الفئة

من الضروري الإشارة إلى عضو في فئة ثابتة من خلال اسم الفئة ، وليس بالإشارة إلى كائن فئة أو عن طريق تعبير يعيد هذا الكائن:

Foo aFoo = ...;
Foo.aStaticMethod(); // 
aFoo.aStaticMethod(); // 
somethingThatYieldsAFoo().aStaticMethod(); //  

6.4 لا تستخدم الصيغ النهائية

من النادر جدًا أن تحتاج إلى تجاوز طريقة Object.finalize.



تلميح :



لا تفعل هذا. إذا كنت في حاجة إليها حقًا ، فاقرأ أولاً وفهم تمامًا عنصر Java الفعال 7 ، وتجنب Finalizers ، ثم لا تفعل.

7. جافادوك

7.1 التنسيق

7.1.1 الشكل الرئيسي

يتبع التنسيق البسيط لكتل ​​Javadoc هذا المثال:

/**
 * Multiple lines of Javadoc text are written here,
 * wrapped normally...
 */
public int method(String p1) { ... }

.. أو في سطر واحد:

/** An especially short bit of Javadoc. */

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

7.1.2 الفقرات

يظهر سطر فارغ واحد ، أي سطر يحتوي فقط على علامة النجمة البادئة (*) ، بين الفقرات وقبل مجموعة علامات الحظر ، إن وجدت. كل فقرة ما عدا الأولى تحتوي على <p> قبل الكلمة الأولى مباشرة ، دون مسافة بعدها.

7.1.3 علامات الحظر

جميع علامات الحظر بالترتيب التالي:param وreturn وthrows وdeprecated وهذه الأنواع الأربعة غير موجودة أبدًا بأوصاف فارغة. إذا كانت علامة كتلة لا تتلاءم مع سطر واحد ، فسيتم وضع مسافة بادئة بين أسطر المتابعة أربعة (أو أكثر) مسافات من @.

7.2 المقتطف النهائي

تبدأ كل كتلة Javadoc بمقتطف موجز قصير. هذا المقتطف مهم جدًا: إنه النص الوحيد الذي يظهر في سياق معين ، مثل فهارس الفئة والطريقة.



هذا المقتطف هو اسم أو عبارة فعل ، وليس جملة كاملة. لا يبدأ بـ A {code Foo} هو ... أو ترجع هذه الطريقة ... ، ولا تشكل جملة مؤكدة كاملة مثل Save the Record. ومع ذلك ، يتم كتابة هذا المقطع بحروف كبيرة ويتخللها علامات الترقيم كما لو كانت جملة كاملة.



تلميح : من الخطأ الشائع كتابة جافادوك بسيط مثل / ** @ استرجاع هوية العميل * /. هذا غير صحيح ويجب تصحيحه إلى / ** إرجاع الرقم التعريفي للعميل. * /.

7.3 عندما يتم تطبيق Javadoc

Javadoc موجود على الأقل في كل فئة عامة وكل عضو عام ومحمي من هذه الفئة ، باستثناء في بعض الحالات ، الموضحة أدناه.

قد يكون Javadoc إضافي موجودًا ، كما هو موضح في القسم 7.3.4 ، Javadoc الاختياري.

7.3.1 استثناء: الأساليب التي تصف نفسها

يعد Javadoc اختياريًا للطرق البسيطة والواضحة مثل getFoo في الحالات التي لا يمكنك فيها قول أكثر من "Returns foo".



هام : من غير المناسب الإشارة إلى هذا الاستثناء لتبرير حذف المعلومات ذات الصلة التي قد يحتاجها القارئ العام.



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

7.3.2 استثناء: تجاوز

لا يصاحب Javadoc دائمًا طريقة تتجاوز طريقة من فئة فائقة (أو واجهة فائقة).

7.3.4 اختياري Javadoc

الفصول والأعضاء الآخرين يرافقهم جافادوك حسب الحاجة أو الرغبة.



عندما يتم استخدام تعليق تنفيذي لتحديد الغرض العام أو سلوك الفصل أو العضو ، تتم كتابة هذا التعليق كـ Javadoc (باستخدام / **).



لا يتعين على Javadoc الاختياري اتباع قواعد التنسيق الواردة في الأقسام 7.1.2 و 7.1.3 و 7.2 ، على الرغم من أن هذا موصى به بالطبع.



هذه الترجمة متاحة أيضًا على مدونتنا.