ملخص قصير لأفضل ممارسات ترميز Java

بناءً على معايير الترميز من قِبل Oracle و Google و Twitter و Spring Framework

الهدف من هذه المقالة هو تزويدك بموجز سريع للأشياء التي لا تفضل وتجنب بمعنى آخر بناءً على معايير الترميز من عمالقة التكنولوجيا مثل Oracle و Google و Twitter و Spring Framework.

قد توافق أو لا توافق على بعض من أفضل الممارسات المقدمة هنا ، وهذا جيد تمامًا طالما يوجد بعض معايير الترميز المعمول بها.

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

يمكن أن تكون وثيقة معايير الترميز طويلة ومملة. يختار كرز المقالة هذه المقاطع والقطع من اتفاقيات الترميز من قِبل Google و Oracle و Twitter و Spring ، والهدف من ذلك هو تزويدك بمتابعة سهلة ومجموعة أقل من الممارسات مملة لتسهيل قراءة التعليمات البرمجية والحفاظ عليها.

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

دعنا ننتقل إلى أفضل الممارسات من معايير الترميز المختلفة.

ملف جافا المصدر

يعتبر ما يلي أفضل الممارسات عندما يتعلق الأمر بملفات مصدر java:

  • طول الملف المصدر أقل من 2000 سطر من التعليمات البرمجية
  • يتم تنظيم الملف المصدر مع التعليق على الوثائق ، وإعلان الحزمة ، متبوعًا بتعليقات الفئة ، والواردات المجمعة (ثابت آخر) ، وتوقيع الفئة / الواجهة وما إلى ذلك كما هو موضح أدناه
حزمة com.example.model ؛
/ **
 * منظور التنفيذ خالية ليتم قراءتها من قبل المطورين
 * الذين قد لا يكون لديهم بالضرورة شفرة المصدر في متناول اليد
 *
 * @ Author x، y، z
 * @تاريخ
 * @الإصدار
 * @حقوق النشر
 *
 * /
استيراد com.example.util.FileUtil؛
/ *
 * اختياري فئة محددة التعليق
 *
 * /
الطبقة العامة SomeClass {
  // متغيرات ثابتة في ترتيب الرؤية
  نهائي ثابت عام Integer PUBLIC_COUNT = 1 ؛
  عدد صحيح ثابت ثابت PROTECTED_COUNT = 1 ؛
  عدد صحيح ثابت ثابت خاص PRIVATE_COUNT = 1 ؛
  // متغيرات مثيل بترتيب الرؤية
  اسم السلسلة العامة ؛
  سلسلة الرمز البريدي ؛
  عنوان السلسلة الخاص
  // منشئ ومثقل بالترتيب التسلسلي
  SomeClass العامة () {}
  SomeClass العامة (اسم السلسلة) {
    this.name = الاسم ؛
  }
  // طرق
  سلسلة عامة doSomethingUseful () {
    إرجاع "شيء مفيد" ؛
  }
  // getters ، setters ، يساوي ، hashCode و toString في النهاية
}

تسمية

أسماء الفئات والواجهة هي CamelCase ومن المستحسن استخدام الكلمة بالكامل وتجنب الاختصارات / الاختصارات. على سبيل المثال فئة النقطية أو فئة ImageSprite

  • الحزمة - أسماء com.deepspace عبر com.deepSpace أو com.deep_space
  • أسماء الملفات هي CamelCase وتنتهي بامتداد java. هناك فئة عامة واحدة لكل ملف مع كل فئة المستوى الأعلى في ملفها
  • الطريقة - يجب أن تكون الأسماء فعلاً في حالة مختلطة مع استخدام كل كلمة داخلية بحروف كبيرة على سبيل المثال run ()؛ أو runFast () ؛
  • الثوابت - يجب أن تكون كبيرة مع "_" تفصل كل كلمة على سبيل المثال int MIN_WIDTH = 44 ؛ و int MAX_WIDTH = 99؛
  • المتغير - اسم يخبر قارئ البرنامج بما يمثله المتغير ، أي إذا كنت تخزن درجة اختبار ثم اختر التقدير مقابل var1. الحفاظ على أسماء المتغيرات قصيرة تجنب بما في ذلك البيانات الوصفية.
// Prefer () - أسماء المتغيرات قصيرة ووصف ما يخزنها
المدرسة الدولية
int [] filteredSchoolIds؛
int [] uniqueSchooldIds؛
خريطة <عدد صحيح ، المستخدم> usersById ؛
قيمة السلسلة؛
// تجنب (x) - تسمية متغيرة مفصلة للغاية
int schoolIdentificationNumber؛
int [] userProvidedSchoolIds؛
int [] schoolIdsAfterRemovingDliclices؛
خريطة <عدد صحيح ، المستخدم> idToUserMap ؛
سلسلة القيمة

تذكر أن الاسم المتغير يجب أن يكون قصيرًا وأن يخبر القارئ بسهولة بالقيمة التي يمثلها. استخدم حكمك.

تفضل وتجنب

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

  • المسافة البادئة - استخدام مسافات 2 أو 4 والبقاء ثابت
  • طول الخط - ما يصل إلى 70 إلى 120 حرفًا بناءً على التأثير على قابلية القراءة. من المهم إلغاء الحاجة إلى التمرير الأفقي وفواصل الأسطر بعد الفاصلة والمشغل.

الأساليب - فيما يلي قائمة بأفضل الممارسات

// Prefer () فواصل الأسطر تعسفية وتكسر بعد فاصلة.
String downloadAnInternet (الإنترنت عبر الإنترنت ، أنابيب أنابيب ،
    مدونات Blogosphere ، النطاق الترددي  bandwidth) {
  tubes.download (الإنترنت)؛
}
/ / تجنب (x) طريقة الفرق الثابت تتطابق مع أسلوب الجسم
String downloadAnInternet (الإنترنت عبر الإنترنت ، أنابيب أنابيب ،
    مدونات Blogosphere ، النطاق الترددي  bandwidth) {
    tubes.download (الإنترنت)؛
}
تفضيل () أضف 8 (ضعف 2 أو 4) مسافات للمسافة البادئة العميقة
ثابت horkingLongMethodName الخاص ثابت (int anArg ،
        كائن آخر ، سلسلة ، سلسلة حتى الآن ،
        كائن و StillAnother) {
  ...
}
تفضيل () سهولة المسح ومساحة عمود إضافية.
سلسلة عامة downloadAnInternet (
    الإنترنت عبر الإنترنت ،
    أنابيب أنابيب
    مدونات المدونات
    المبلغ <طول ، بيانات> عرض النطاق الترددي) {
  tubes.download (الإنترنت)؛
  ...
}
اختبار وحدة قد اشتعلت ذلك

If-checks - كتابة المنظمة البحرية الدولية لرمز جيد التنسيق يجعل من السهل اكتشاف الأخطاء المطبعية والأخطاء للمؤلف والمراجعين رمز ، انظر أدناه:

// تجنب (x) لا تتجاهل {}
إذا (شرط)
  بيان؛
// تجنب (س)
إذا (س <0) سالب (س) ؛
// تجنب (س)
if (a == b && c == d) {
...
}
// تفضل ()
إذا ((a == b) && (c == d)) {
...
}
// تفضل ()
إذا (الحالة) {
  صياغات؛
} آخر إذا (شرط) {
  صياغات؛
} آخر إذا (شرط) {
  صياغات؛
}
// تجنب (س)
إذا ((condition1 && condition2)
    || (condition3 && condition4)
    ||! (condition5 && condition6)) {// BAD WRAPS
    إفعل شيا حيال هذا()؛ / / اجعل هذا الخط سهلاً
}
// تفضل ()
إذا ((condition1 && condition2)
        || (condition3 && condition4)
        ||! (condition5 && condition6)) {
    إفعل شيا حيال هذا()؛
}

المشغل الثلاثي - وفيما يلي الممارسات الموصى بها

ألفا = (aLongBooleanExpression)؟ beta: gamma؛
ألفا = (aLongBooleanExpression)؟ بيتا
        : جاما ؛
ألفا = (aLongBooleanExpression)
        ؟ بيتا
        : جاما ؛

التبديل - عندما يتعلق الأمر بالتبديل ، فمن الأفضل ممارسة

  • دائما حالة افتراضية حتى من دون رمز
  • استخدام / * يقع خلال * / للإشارة إلى سقوط عنصر التحكم في الحالة التالية
التبديل (الحالة) {
  القضية ABC:
    صياغات؛
  /* يقع من خلال */
  حالة الدفاع:
    صياغات؛
    استراحة؛
  الإفتراضي:
    صياغات؛
     استراحة؛
}

رسائل الاستثناء - عند تقديم استثناء هنا ، توجد عينات من الرسائل الجيدة ذات المسافات البادئة.

// تجنب (x) - ليس من السهل قراءتها
رمي IllegalStateException الجديد ("فشل في معالجة طلب" + request.getId ()
    + "للمستخدم" + user.getId () + "استعلام:" "+ query.getText ()
    + "" ") ؛
// تفضل () - أسهل إلى حد ما في القراءة
رمي IllegalStateException الجديد ("فشل في المعالجة"
    + "طلب" + request.getId ()
    + "للمستخدم" + user.getId ()
    + "query: '" + query.getText () + "" ")؛

تكرارات وتيارات - أصبحت التدفقات أكثر شيوعًا وفي بعض الأحيان قد تكون معقدة للغاية ، من المهم أن تكون المسافة البادئة سهلة القراءة.

// تجنب (x) - ليس من السهل قراءتها
الوحدات النمطية  Iterable = ImmutableList.  builder (). add (LifecycleModule () جديدة)
    .add (جديد AppLauncherModule ()). addAll (application.getModules ()). build ()؛
// تفضل () - أسهل إلى حد ما في القراءة
الوحدات النمطية  Iterable = قائمة غير قابلة للتطبيق.  builder ()
    .add (جديد LifecycleModule ())
    .add (جديد AppLauncherModule ())
    .addAll (application.getModules ())
    . البناء ()؛
فقط اتبع معيار الترميز - أي حقا

الإعلانات والتخصيصات - يوصى بإعلان واحد في كل سطر لأنه يشجع التعليقات كما هو موضح أدناه.

// تفضل ()
مستوى كثافة العمليات ؛ // مستوى المسافة البادئة
حجم الباحث // حجم الجدول
// تجنب (س) لصالح أعلاه
مستوى int ، sizeMeter.
// Prefer () - تضمين وحدة في اسم متغير أو نوع
pollIntervalMs طويلة ؛
int fileSizeGb ؛
المبلغ <عدد صحيح ، بيانات> fileSize ؛
/ / تجنب (x) أنواع الخلط
int foo، fooarray []؛
// تجنب (x) - لا تفصل بينها فاصلة
Format.print (System.out، "error")، exit (1)؛
// تجنب (x) مهمة متعددة
fooBar.fChar = barFoo.lchar = 'c'؛
// تجنب (x) الواجبات المضمنة في محاولة لزيادة الأداء // أو حفظ الخط. أنا مذنب من القيام بذلك :(
د = (أ = ب + ج) + ص ؛
// تفضل () أعلاه
أ = ب + ج ؛
د = أ + ص ؛
// تفضل ()
سلسلة [] الحجج
// تجنب (س)
سلسلة الحجج []
تفضيل () استخدم طويلاً "L" بدلاً من "l" لتجنب الالتباس مع 1
مهلة طويلة = 3000000000L ؛
// تجنب (x) - من الصعب معرفة الحرف الأخير هو l وليس 1
مهلة طويلة = 3000000000l ؛

ضع التعريفات فقط في بداية الكتل (الكتلة عبارة عن كود محاط بأقواس مجعد {و}). لا تنتظر إعلان المتغيرات حتى استخدامها لأول مرة ؛ يمكن أن تخلط بين مبرمج غير مرغوب فيه وتعرقل قابلية نقل الرمز ضمن النطاق.

// تفضيل () تعلن في بداية الكتلة.
باطل عام doSomething () {
  الباحث: // بداية كتلة الطريقة
  إذا (الحالة) {
    int someFlag. // بداية كتلة "if"
    ...
  }
}

من المهم أيضًا تجنب الإعلانات المحلية التي تخفي إعلانات المستويات العليا وتجنب الالتباسات كما هو موضح أدناه

عدد العد
...
باطل عام doSomething () {
  إذا (الحالة) {
    عدد العد // تجنب!
    ...
  }
  ...
}

التباعد وفواصل الأسطر - تجنب إغراء توفير 1-2 أسطر من الشفرات على حساب قابلية القراءة. فيما يلي أفضل الممارسات عندما يتعلق الأمر بالتباعد وخطوط فارغة (مساحة بيضاء تحدث فرقًا)

  • يوصي سطر واحد (1) فارغ بين الأساليب ومطوري Spring بسطرين (2) فارغين بعد المُنشئات والكتل الثابتة والحقول والطبقة الداخلية
  • مشغلي الوسائد الفضائية ، أي استخدم int foo = a + b + 1؛ على int foo = a + b + 1 ؛
  • افصل جميع العوامل الثنائية باستثناء "." عن المعاملات التي تستخدم مسافة
  • تظهر الدعامة المفتوحة "{" في نهاية نفس السطر مثل بيان أو طريقة التصريح ويبدأ إغلاق القوس "}" بسط المسافة البادئة
// Prefer () - المسافة بعد "بينما" وقبل "("
احيانا صحيح) {
  ...
}
// تجنب (x) - على عكس لا توجد مساحة
احيانا صحيح) {
  ...
}
// Prefer () - لا توجد مسافة بين "doSomething" و "("
باطل عام doSomething () {
  ...
}
// تجنب (x) - على عكس الفضاء
باطل عام doSomething () {
  ...
}
// Prefer () - أضف مسافة بعد وسيطة
الفراغ العام لاشيء (int a، int b) {
  ...
}
// Prefer () - المسافة بين المعامل والمعاملات (بمعنى + ، =)
a + = c + d؛
a = (a + b) / (c * d) ؛
بينما (d ++ = s ++) {
  ن ++؛
}

الوثائق والتعليقات

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

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

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

تعليقات التنفيذ - يُقصد بها التعليق على الكود أو التعليق على تطبيق معين للكود.

تعليقات الوثائق - يُقصد بها وصف مواصفات الكود من منظور خالٍ من التطبيق ليتم قراءته من قبل المطورين الذين قد لا يكون لديهم الكود المصدري بالضرورة.

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

أنواع تعليقات التنفيذ

هناك أربعة (4) أنواع من تعليقات التنفيذ كما هو موضح أدناه

  • حظر التعليق - انظر المثال أدناه
  • تعليق سطر مفرد - عندما لا يكون التعليق أطول من سطر
  • التعليقات الزائدة - تم نقل تعليق قصير جدًا إلى الطرف الأيمن
  • تعليق نهاية السطر - يبدأ التعليق الذي يستمر حتى السطر الجديد. يمكنه التعليق على سطر كامل أو سطر جزئي فقط. لا ينبغي استخدامه على أسطر متعددة متتالية للتعليقات النصية ؛ ومع ذلك ، يمكن استخدامه في أسطر متعددة متتالية للتعليق على مقاطع التعليمات البرمجية.
// تعليق بلوك
/ *
 * الاستخدام: يوفر وصفا للملفات والأساليب وهياكل البيانات
 * والخوارزميات. يمكن استخدامها في بداية كل ملف و
 * قبل كل طريقة. تستخدم للتعليقات الطويلة التي لا تناسب
 * سطر واحد. 1 سطر فارغ للمتابعة بعد تعليق الكتلة.
 * /
// سطر تعليق واحد
إذا (الحالة) {
 / * التعامل مع الشرط. * /
  ...
}
// تعليق زائدة
إذا (أ = 2) {
 عودة TRUE ؛ /* حالة خاصة */
} آخر {
 عودة isPrime (أ) ؛ / * يعمل فقط للغريب * /
}
// نهاية سطر التعليق
إذا (فو> 1) {
  // افعل الوجه المزدوج.
  ...
} آخر {
  عودة كاذبة؛ // اشرح لماذا هنا.
}
// if (bar> 1) {
//
// // افعل الوجه الثلاثي.
// ...
//}
//آخر
// عودة كاذبة؛

تعليقات الوثائق (أي Javadoc)

Javadoc هي أداة تنشئ وثائق HTML من شفرة java الخاصة بك باستخدام التعليقات التي تبدأ بـ / ** وتنتهي بـ * / - راجع Wikipedia للحصول على مزيد من التفاصيل حول كيفية عمل Javadoc أو مجرد قراءته.

هنا مثال على Javadoc

/ **
 * إرجاع كائن صورة يمكن بعد ذلك رسمه على الشاشة.
 * يجب أن تحدد وسيطة عنوان url {link URL} مطلقًا. الاسم
 * الوسيطة هي محدد نسبة إلى وسيطة url.
 * 

 * هذه الطريقة تعود دائما على الفور ، سواء كان أو لم يكن  * الصورة موجودة. عندما يحاول هذا التطبيق الصغير رسم الصورة  * الشاشة ، سيتم تحميل البيانات. الرسومات بدائية  * التي رسم الصورة سوف ترسم تدريجيا على الشاشة.  *  *param url عنوان URL مطلق يعطي الموقع الأساسي للصورة  *param اسم موقع الصورة ، نسبة إلى وسيطة رابط  * @ أعد الصورة في عنوان URL المحدد  * @ انظر الصورة  * /  getImage للصور العامة (عنوان URL ، اسم السلسلة) {         محاولة {             return getImage (عنوان URL جديد (عنوان url ، الاسم)) ؛         } catch (MalformedURLException e) {             عودة لاغية         }  }

وما سبق قد ينتج عنه HTML كما يلي عندما يتم تشغيل javadoc مقابل الكود الذي يحتوي على ما سبق

انظر هنا للمزيد

فيما يلي بعض العلامات الأساسية التي يمكنك استخدامها لتحسين جودة وثائق جافا التي تم إنشاؤها.

author =>author Raf
code => {code A  C}
deprecated => @ إهمال - رسالة إهمال
exception =>exception تم طرح IOException عندما
link => {link package.class # member label}
param =>param وصف اسم المعلمة
return => ما هي الطريقة التي يتم إرجاعها
see =>see "string" أوsee  
since => للإشارة إلى الإصدار عند إضافة طريقة متاحة للجمهور

للحصول على قائمة كاملة ووصف أكثر تفصيلا انظر هنا

ينصح معيار ترميز Twitter بعدم استخدام علامةauthor

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

فيما يلي أمثلة على الطريقة التي يمكنك بها كتابة تعليق بالوثائق يكون ثاقبًا كما هو موضح في معيار ترميز Twitter

// سيئة.
// - لا يقول المستند شيئًا عن أن طريقة الإعلان لم تذكر.
// - هذا هو "حشو الوثيقة". سوف يمر الشيكات الاسلوب ، ولكن
لا يساعد أي شخص.
/ **
 * انشقاقات سلسلة.
 *
 * @ بارام s سلسلة.
 *return قائمة السلاسل.
 * /
قائمة <سلسلة> الانقسام (سلسلة) ؛
// أفضل.
// - نحن نعرف ماذا تنقسم الطريقة.
// - لا يزال بعض السلوك غير معروف.
/ **
 * انشقاقات سلسلة على مسافة بيضاء.
 *
 * @ بارام s السلسلة لتقسيم. تتم معاملة سلسلة {code null} كسلسلة فارغة.
 *return قائمة بالأجزاء المحددة بمدخلات بيضاء.
 * /
قائمة <سلسلة> الانقسام (سلسلة) ؛
// عظيم.
// - يغطي حالة حافة أخرى.
/ **
 * انشقاقات سلسلة على مسافة بيضاء. شخصيات بيضاء متكررة
 * انهارت.
 *
 * @ بارام s السلسلة لتقسيم. تتم معاملة سلسلة {code null} كسلسلة فارغة.
 *return قائمة بالأجزاء المحددة بمدخلات بيضاء.
 * /
قائمة <سلسلة> الانقسام (سلسلة) ؛

من المهم أن تكون محترفًا عندما يتعلق الأمر بكتابة التعليقات

// تجنب (س)
/ / أنا أكره xml / صابون كثيرًا ، فلماذا لا يفعل هذا من أجلي؟
محاولة {
  userId = Integer.parseInt (xml.getField ("id")) ؛
} catch (NumberFormatException e) {
  ...
}
// تفضل ()
// TODO (Jim): التحقق من صحة حقل الثنية بعيدًا في المكتبة.
محاولة {
  userId = Integer.parseInt (xml.getField ("id")) ؛
} catch (NumberFormatException e) {
  ...
}

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

وهنا بعض النقاط القليلة التي يجب وضعها في الاعتبار

  • تجنب استيراد أحرف البدل - كما هو موضح في معايير الترميز على Twitter ، يجعل مصدر الفصل أقل وضوحًا. أنا أعمل في فريق مع مزيج من مستخدمي Eclipse و IntelliJ ووجدت أن Eclipse يزيل استيراد أحرف البدل ويقوم IntelliJ بتقديمه. ربما هناك خيار لإيقاف تشغيله ، أردت فقط أن أشير إلى الافتراضي للاثنين.
  • استخدم دائمًا التعليقات التوضيحية @ Override عند تجاوزها
  • شجع استخدام @ Nullable عندما يعود حقل أو طريقة خالية
  • استفد من التعليقات الخاصة للعمل المستقبلي ولا تنسَ أن تترك مرجعًا لنفسك حتى يعرف الآخرون من يسأل سؤال Y الخاص بهم بدلاً من التخمين أو إزالته أو التحقق من إلقاء اللوم للعثور على من أضافه. تساعد بعض IDEs مثل Eclipse و IntelliJ أيضًا في إدراجها لسهولة الوصول إليها بالإضافة إلى تذكير.
// FIXME (Raf): تصف رسالة قابلة للتنفيذ ما يجب القيام به
// TODO (Raf): تصف رسالة قابلة للتنفيذ ما يجب القيام به

اللعبة النهائية هي كتابة التعليمات البرمجية التي تجعل حياة المؤلفين والمحافظين في المستقبل سهلة.

لعبة النهاية

مواد القراءة الأخرى ذات الصلة

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

وقائمة جيدة أخرى من النصائح لكتابة رمز نظيف