ما هو التعليق التوضيحي:
التعليق التوضيحي (التعليق التوضيحي) هو طريقة وطريقة توفرها Java لربط أي معلومات وأي بيانات وصفية (بيانات التعريف) مع العناصر الموجودة في البرنامج التعريفي. التعليق التوضيحي (التعليق التوضيحي) عبارة عن واجهة يمكن للبرنامج الحصول على كائن التعليق التوضيحي لعنصر البرنامج المحدد من خلال الانعكاس، ثم الحصول على البيانات التعريفية في التعليق التوضيحي من خلال كائن التعليق التوضيحي.
تم تقديم التعليق التوضيحي (التعليق التوضيحي) في JDK5.0 والإصدارات الأحدث. يمكن استخدامه لإنشاء الوثائق، وتتبع التبعيات في التعليمات البرمجية الخاصة بك، وحتى إجراء فحوصات وقت الترجمة الأساسية. في بعض النواحي، يتم استخدام التعليقات التوضيحية مثل المعدلات ويتم تطبيقها على إعلان الحزم والأنواع والمنشئات والأساليب ومتغيرات الأعضاء والمعلمات والمتغيرات المحلية. يتم تخزين هذه المعلومات في زوج بنية "الاسم = القيمة" للتعليق التوضيحي.
يتم الإعلان عن أعضاء التعليق التوضيحي كطرق بدون معلمات في نوع التعليق التوضيحي. يحدد اسم الطريقة وقيمة الإرجاع اسم العضو ونوعه. يوجد بناء جملة افتراضي محدد هنا: يُسمح بإعلان القيمة الافتراضية لأي عضو تعليق توضيحي: يمكن للتعليق التوضيحي استخدام زوج الاسم = القيمة كقيمة لعضو التعليق التوضيحي الذي لا يحدد قيمة افتراضية بالطبع يمكن أيضًا استخدام زوج القيمة لتجاوز القيمة الافتراضية للأعضاء الآخرين. يشبه هذا إلى حد ما خصائص وراثة الفئات. يمكن استخدام مُنشئ الفئة الأصلية كمُنشئ افتراضي للفئة الفرعية، ولكن يمكن أيضًا تجاوزه بواسطة الفئة الفرعية.
يمكن استخدام التعليقات التوضيحية لربط أي معلومات بعنصر برنامج (الفئة، الطريقة، متغير العضو، وما إلى ذلك). تجدر الإشارة إلى أن هناك قاعدة أساسية هنا: لا يمكن أن يؤثر التعليق التوضيحي على تنفيذ كود البرنامج، بغض النظر عما إذا تمت إضافة التعليق التوضيحي أو حذفه، فسيتم تنفيذ التعليمات البرمجية بشكل متسق. بالإضافة إلى ذلك، على الرغم من أنه يتم الوصول إلى بعض التعليقات التوضيحية في وقت التشغيل من خلال أساليب واجهة برمجة تطبيقات الانعكاس الخاصة بـ Java، إلا أن مترجم لغة Java يتجاهل هذه التعليقات التوضيحية أثناء العمل. نظرًا لأن جهاز Java الظاهري يتجاهل التعليق التوضيحي، فإن نوع التعليق التوضيحي "لا يعمل" في الكود؛ ولا يمكن الوصول إلى المعلومات الموجودة في نوع التعليق التوضيحي ومعالجتها إلا من خلال بعض الأدوات الداعمة. ستغطي هذه المقالة أنواع التعليقات التوضيحية والتعليقات التوضيحية القياسية. الأداة المصاحبة لأنواع التعليقات التوضيحية هذه هي مترجم Java (الذي يتعامل معها بالطبع بطريقة خاصة).
-------------------------------------------------- ----------------------------------
ما هي البيانات الوصفية (البيانات الوصفية):
يتم ترجمة البيانات الوصفية من كلمة البيانات الوصفية، والتي تعني "بيانات حول البيانات".
تحتوي البيانات التعريفية على العديد من الوظائف، على سبيل المثال، ربما تكون قد استخدمت تعليقات Javadoc لإنشاء الوثائق تلقائيًا. هذا هو أحد أنواع وظائف البيانات الوصفية. بشكل عام، يمكن استخدام بيانات التعريف لإنشاء الوثائق، وتتبع تبعيات التعليمات البرمجية، وإجراء فحوصات تنسيق وقت الترجمة، واستبدال ملفات التكوين الموجودة. إذا أردنا تصنيف دور البيانات الوصفية، فلا يوجد حاليًا تعريف واضح، ولكن يمكننا تقسيمها تقريبًا إلى ثلاث فئات بناءً على دورها:
1. كتابة المستندات: إنشاء المستندات من خلال البيانات التعريفية المحددة في الكود 2. تحليل الكود: تحليل الكود من خلال البيانات التعريفية المحددة في الكود 3. التحقق من التجميع: باستخدام البيانات التعريفية المحددة في الكود، يمكن للمترجم تحقيق التجميع الأساسي التحقق من ذلك توجد البيانات الوصفية في Java في كود Java على شكل علامات، ولا يؤثر وجود علامات البيانات الوصفية على تجميع وتنفيذ كود البرنامج معلومة.
في ملخص:
أولاً، توجد البيانات الوصفية في كود Java على شكل علامات.
ثانيًا، المعلومات التي تصفها بيانات التعريف آمنة من حيث النوع، أي أن الحقول الموجودة في بيانات التعريف لها أنواع واضحة.
ثالثًا، تتطلب البيانات الوصفية معالجة إضافية بواسطة أدوات أخرى غير المترجم المستخدم لإنشاء مكونات البرنامج الأخرى.
رابعًا، يمكن أن توجد البيانات التعريفية فقط على مستوى كود مصدر Java، أو يمكن أن توجد داخل ملف Class المترجم.
-------------------------------------------------- ----------------------------------
أنواع الحواشي والتعليقات التوضيحية:
تعليق توضيحي:
يستخدم التعليق التوضيحي بناء الجملة الجديد الذي تم تقديمه في Java5.0، ويشبه سلوكه إلى حد كبير المعدلات مثل العامة والنهائية. كل تعليق توضيحي له اسم وعدد الأعضاء >=0. كل عضو في التعليق التوضيحي له اسم وقيمة تسمى زوج الاسم=القيمة (تمامًا مثل javabean)، ويقوم الاسم=القيمة بتحميل معلومات التعليق التوضيحي.
نوع التعليق التوضيحي:
يحدد نوع التعليق التوضيحي الاسم والنوع والقيمة الافتراضية للعضو للتعليق التوضيحي. يمكن القول أن نوع التعليق التوضيحي عبارة عن واجهة Java خاصة، وأن متغيرات أعضائه مقيدة، ويلزم بناء جملة جديد عند الإعلان عن نوع التعليق التوضيحي. عندما نصل إلى التعليق التوضيحي من خلال واجهة برمجة تطبيقات انعكاس Java، ستكون القيمة المرجعة عبارة عن كائن ينفذ واجهة نوع التعليق التوضيحي. من خلال الوصول إلى هذا الكائن، يمكننا الوصول بسهولة إلى أعضاء التعليق التوضيحي الخاص به. ستذكر الفصول التالية أنواع التعليقات التوضيحية الثلاثة القياسية المضمنة في حزمة java.lang الخاصة بـ java5.0.
-------------------------------------------------- ----------------------------------
فئات التعليقات التوضيحية:
وفقًا لعدد معلمات التعليقات التوضيحية، يمكننا تقسيم التعليقات التوضيحية إلى ثلاث فئات:
1. التعليق التوضيحي للعلامة: يُطلق على نوع التعليق التوضيحي بدون تعريف العضو اسم التعليق التوضيحي للعلامة. يستخدم هذا النوع من التعليقات التوضيحية وجوده أو غيابه فقط لتزويدنا بالمعلومات. على سبيل المثال، التعليق التوضيحي للنظام التالي @Override؛
2. تعليق توضيحي بقيمة واحدة 3. شرح كامل
وفقًا لاستخدام التعليقات التوضيحية والغرض منها، يمكننا تقسيم التعليقات التوضيحية إلى ثلاث فئات:
1. التعليقات التوضيحية لنظام JDK المدمج 2. التعليقات التوضيحية التعريفية 3. التعليقات التوضيحية المخصصة
-------------------------------------------------- ----------------------------------
التعليقات التوضيحية القياسية المضمنة في النظام:
بناء جملة التعليقات التوضيحية بسيط نسبيًا، باستثناء استخدام الرمز @، فهو متوافق بشكل أساسي مع بناء الجملة الأصلي لـ Java. هناك ثلاثة تعليقات توضيحية قياسية مدمجة في JavaSE، والتي تم تعريفها في java.lang:
@Override: يستخدم لتعديل هذه الطريقة لتجاوز طريقة الفئة الأصل؛
@Deprecated: يُستخدم لتعديل الأساليب القديمة؛
@SuppressWarnings: يُستخدم لإعلام مترجم Java بمنع تحذيرات التحويل البرمجي المحددة.
دعونا نلقي نظرة على الوظائف وسيناريوهات الاستخدام للتعليقات التوضيحية القياسية الثلاثة المضمنة بدورها.
-------------------------------------------------- ----------------------------------
@Override، تقييد تجاوز أساليب الفئة الأصل:
@Override هو نوع تعليق توضيحي للعلامة يُستخدم للتعليق على الطرق. يوضح أن الطريقة المشروحة تفرط في تحميل طريقة الفئة الأصلية وتلعب دور التأكيد. إذا استخدمنا هذا النوع من التعليقات التوضيحية بطريقة لا تتجاوز طريقة الفئة الأصلية، فسيحذرك مترجم Java من حدوث خطأ في الترجمة. غالبًا ما يتم تشغيل هذا التعليق التوضيحي عندما نحاول تجاوز طريقة الفئة الأصلية ولكننا نكتب اسم الطريقة الخاطئة. الاستخدام بسيط للغاية: عند استخدام هذا التعليق التوضيحي، ما عليك سوى إضافة @Override أمام الطريقة المعدلة. التعليمة البرمجية التالية هي مثال لاستخدام @Override لتعديل طريقة DisplayName() لمحاولة تجاوز الفئة الأصل، ولكن هناك أخطاء إملائية:
اسم عرض الفراغ العام () {
System.out.println("اسم الفاكهة: *****");
}
}
صنف برتقالي يمتد ثمرة {
@تجاوز
اسم عرض الفراغ العام () {
System.out.println("اسم الفاكهة: برتقالي");
}
}
صنف التفاح يمتد الفاكهة {
@تجاوز
اسم عرض الفراغ العام () {
System.out.println("اسم الفاكهة: تفاحة");
}
}
@Deprecated، تم إهمال العلامة:
وبالمثل، يعد Deprecated أيضًا تعليقًا توضيحيًا ترميزيًا. عندما يتم تزيين نوع أو عضو نوع بـ @Deprecated، فلن يشجع المترجم استخدام عنصر البرنامج المشروح هذا. وهذا النوع من التعديل له درجة معينة من "الاستمرارية": إذا استخدمنا هذا النوع أو العضو القديم في الكود من خلال الميراث أو الكتابة الفوقية، على الرغم من عدم الإعلان عن النوع أو العضو الموروث أو المتجاوز @Deprecated، فلا يزال يتعين على المترجم التحذير أنت.
تجدر الإشارة إلى أن هناك اختلافًا بين نوع التعليق التوضيحي @Deprecated والعلامة @deprecated في javadoc: يتم التعرف على الأول بواسطة مترجم Java، بينما يتم التعرف على الأخير بواسطة أداة javadoc ويتم استخدامه لإنشاء الوثائق (بما في ذلك لماذا البرنامج الأعضاء عفا عليها الزمن، ووصفه كيف ينبغي حظره أو استبداله).
في Java 5.0، لا يزال مترجم Java يبحث عن علامات Javadoc @deprecated ويستخدمها لإنشاء رسائل تحذير كما فعل في الإصدارات السابقة. لكن هذا الوضع سيتغير في الإصدارات اللاحقة، ويجب أن نبدأ باستخدام @Deprecated الآن لتزيين الأساليب المهملة بدلاً من علامة @deprecated javadoc.
في البرنامج التالي، يتم استخدام التعليق التوضيحيDeprecated لوضع علامة على الطريقة على أنها منتهية الصلاحية، وفي الوقت نفسه، يتم استخدام العلامة @deprecated في التعليق التوضيحي على الطريقة لوضع علامة على الطريقة على أنها منتهية الصلاحية.
/**
* @deprecated انتهت صلاحية هذه الطريقة ولا ينصح بها.
*/
@مهمل
عرض الفراغ العام () {
System.out.println("طعم التفاح الفاكهي: هش وحلو");
}
عرض الفراغ العام (int typeId) {
إذا (معرف النوع==1){
System.out.println("طعم فاكهة التفاح: حامض");
}
آخر إذا(typeId==2){
System.out.println("طعم التفاح الفاكهي: حلو");
}
آخر{
System.out.println("طعم التفاح الفاكهي: هش وحلو");
}
}
}
فئة عامة FruitRun {
/**
* @param args
*/
public static void main(String[] args) {
Apple apple=new Apple();
apple.displayName();
AppleService appleService=new AppleService();
appleService.showTaste();
appleService.showTaste(0);
appleService.showTaste(2);
}
}
-------------------------------------------------- ----------------------------------
قمع التحذيرات، قمع تحذيرات المترجم:
يتم استخدام @SuppressWarnings لإيقاف تشغيل تحذيرات المترجم بشكل انتقائي للفئات والأساليب ومتغيرات الأعضاء وتهيئة المتغير. في Java5.0، يوفر لنا مترجم javac الذي توفره شركة Sun خيار -Xlint لتمكين المترجم من التحذير من التعليمات البرمجية القانونية للبرنامج، ويمثل هذا التحذير خطأً في البرنامج إلى حد ما. على سبيل المثال، عندما نستخدم فئة مجموعة عامة دون تحديد نوعها، سيطالبك المترجم بتحذير "تحذير لم يتم التحقق منه". عادةً عندما يحدث هذا، نحتاج إلى العثور على الرمز الذي تسبب في التحذير. إذا كان يمثل خطأً حقًا، فيجب علينا تصحيحه. على سبيل المثال، إذا كانت رسالة التحذير تشير إلى أن عبارة التبديل في الكود الخاص بنا لا تغطي جميع الحالات المحتملة، فيجب علينا إضافة حالة افتراضية لتجنب هذا التحذير.
في بعض الأحيان لا يمكننا تجنب هذا التحذير، على سبيل المثال، لا يمكننا تجنب هذا التحذير غير المحدد عندما نستخدم فئة مجموعة عامة يجب أن تتفاعل مع التعليمات البرمجية القديمة غير العامة. سيكون @SuppressWarning مفيدًا في هذا الوقت، أضف تعديل @SuppressWarnings قبل الطريقة المستدعىة لإخبار المترجم بالتوقف عن التحذير بشأن هذه الطريقة.
SuppressWarning ليس تعليقًا توضيحيًا ترميزيًا. يحتوي على عضو من النوع String[]، وقيمة هذا العضو هي اسم التحذير المحظور. بالنسبة للمترجم javac، فإن أسماء التحذير الصالحة للخيار -Xlint صالحة أيضًا لـ @SuppressWarings، ويتجاهل المترجم أسماء التحذير غير المعروفة.
يسمح بناء جملة التعليق التوضيحي بأن يتبع اسم التعليق التوضيحي بين قوسين اسم مفصول بفواصل = أزواج قيمة تستخدم لتعيين قيم لأعضاء التعليق التوضيحي. الأمثلة هي كما يلي:
@SuppressWarnings(value={ "الأنواع الأولية"، "غير محددة" })
القائمة الثابتة العامة<Fruit> getFruitList(){
List<Fruit> FruitList=new ArrayList();
إرجاع قائمة الفاكهة؛
}
@SuppressWarnings({ "الأنواع الأولية"، "غير محددة" })
القائمة الثابتة العامة<Fruit> getFruit(){
List<Fruit> FruitList=new ArrayList();
إرجاع قائمة الفاكهة؛
}
@SuppressWarnings("غير مستخدم")
public static void main(String[] args){
List<String> strList=new ArrayList<String>();
}
}
وصف موجز لقيم المعلمات الشائعة المشروحة بواسطة SuppressWarnings:
1.الإهمال: تحذير عند استخدام الفئات أو الأساليب المهملة؛
2. غير محدد: تحذير عند إجراء تحويل غير محدد، على سبيل المثال، عند استخدام مجموعة، لا يتم استخدام الأدوية العامة لتحديد نوع المجموعة المحفوظة؛
3.fallthrough: تحذير عندما تؤدي كتلة برنامج التبديل مباشرة إلى الموقف التالي دون انقطاع؛
4.path: تحذير عند عدم وجود مسارات في مسار الفصل، أو مسار الملف المصدر، وما إلى ذلك؛
5.serial: تحذير عندما يكون تعريف serialVersionUID مفقودًا في فئة قابلة للتسلسل؛
6.أخيرًا: تحذير عند عدم إمكانية إكمال أي جملة نهائية بشكل طبيعي؛
7.الكل: التحذير من جميع الحالات المذكورة أعلاه.