فهم تعليقات Java التوضيحية - تعليمي Java @ Annotations

نشرت: 2019-10-22
التعليقات التوضيحية على مستوى الحزمة

كيف وأين يتم استخدام التعليقات التوضيحية في Java؟

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

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

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

تحدد Java مجموعة من التعليقات التوضيحية المضمنة في اللغة.

فهم شروح Java التوضيحية - تلميحات Crunchify
فهم شروح Java التوضيحية - تلميحات Crunchify

تم تطبيق التعليقات التوضيحية على كود جافا:

  • Override - للتحقق من أن الوظيفة تجاوزت. يتسبب في تحذير الترجمة إذا لم يتم العثور على الوظيفة في أحد الفئات الرئيسية.
  • Deprecated - لوضع علامة على الوظيفة على أنها قديمة. يتسبب في تحذير الترجمة إذا تم استخدام الوظيفة.
  • SuppressWarnings - يوجه المترجم إلى منع تحذيرات وقت الترجمة المحددة في معلمات التعليق التوضيحي.

تم تطبيق التعليقات التوضيحية على التعليقات التوضيحية الأخرى:

  • Retention - تحدد كيفية تخزين التعليق التوضيحي المحدد — سواء في التعليمات البرمجية فقط ، أو تم تجميعها في الفصل الدراسي ، أو متوفرة في وقت التشغيل من خلال الانعكاس.
  • Documented - لوضع علامة على تعليق توضيحي آخر لتضمينه في الوثائق.
  • Target - لوضع علامة على تعليق توضيحي آخر لتقييد نوع عناصر جافا التي يمكن تطبيق التعليق التوضيحي عليها.
  • @ موروث - لوضع علامة على تعليق توضيحي آخر ليتم توريثه إلى الفئات الفرعية للفئة المشروحة (بشكل افتراضي ، لا يتم توريث التعليقات التوضيحية إلى الفئات الفرعية).

دعنا نلقي نظرة على هذه الأمثلة عبر عينة:

1)Override تعليق توضيحي:

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

حالة الاستخدام الأكثر شيوعًا لـ Override هي طرق الكائن :

1
2
3
4
@ Override
public int hashValue ( ) {
     System . out . Println ( "This method is using @Override Annotation" ) ;
}

السبب الرئيسي وراء إنشاء Override هو التعامل مع الأخطاء المطبعية البسيطة.

على سبيل المثال ، طريقة تم إعلانها عن طريق الخطأ باسم

1
public int hashvalue ( ) { . . . }

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

يجب أن تكون معتادًا على استخدام Override كلما تجاوزت طريقة الطبقة الفائقة.

فهم شروح Java التوضيحية

2) @ تعليق توضيحي مهمل:

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

عندما يتم إهمال عنصر ما ، يجب أيضًا توثيقه باستخدام @deprecated tag ، كما هو موضح في المثال التالي.

1
2
3
4
< strong > @ Deprecated < / strong >
static void deprecatedMethod ( ) {
     System . out . Println ( "This method is Deprecated.." ) ;
}

3)SuppressWarnings تعليق توضيحي:

فقط أخبر المترجم ، من فضلك لا تصرخ. أنا أعرف ما أفعله.

1
2
3
4
@ SuppressWarnings ( "serial" )
public class OldCode implements Serializable {
System . out . Println ( "This is Old Code.." ) ;
}

4) @ تعليق تعليق:

يشير التعليق التوضيحي للاحتفاظ إلى مكان ومدة الاحتفاظ بالتعليقات التوضيحية بهذا النوع.

هناك ثلاث قيم:

  • RetentionPolicy.SOURCE - سيتم الاحتفاظ بالتعليقات بهذا النوع فقط على مستوى المصدر وسيتم تجاهلها من قبل المترجم.
  • RetentionPolicy.CLASS - سيتم الاحتفاظ بالتعليقات بهذا النوع من قبل المترجم في وقت الترجمة ، ولكن سيتم تجاهلها بواسطة VM.
  • RetentionPolicy.RUNTIME - سيتم الاحتفاظ بالتعليقات بهذا النوع بواسطة الجهاز الظاهري بحيث يمكن قراءتها فقط في وقت التشغيل.
1
2
3
4
@ Retention ( RetentionPolicy . RUNTIME )
public @ interface Crunchify_Retention {
   String returnSomething ( ) ;
}

5) @ تعليق توضيحي موثق:

1
2
3
4
@ Documented
public @ interface Crunchify_Documented {
   String writeDocument ( ) ;
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
public class DocumentedAnnotations {
   public static void main ( String arg [ ] ) {
       new DocumentedAnnotations ( ) . performRetention ( ) ;
       new DocumentedAnnotations ( ) . performDocumented ( ) ;
   }
   @ Crunchify_Retention ( returnSomething = "Hello retention test" )
   public void performRetention ( ) {
       System . out . printf ( "Testing annotation 'Crunchify_Retention'" ) ;
   }
   @ Crunchify_Documented ( writeDocument = "Hello document" )
   public void performDocumented ( ) {
       System . out . printf ( "Testing annotation 'Crunchify_Documented'" ) ;
   }
}

حاول الآن تشغيل أمر Java Doc وانظر الإخراج.

6) @ التعليق التوضيحي المستهدف:

يشير الهدف إلى عنصر (عناصر) البرنامج الذي يمكن التعليق عليه باستخدام مثيلات نوع التعليق التوضيحي. قيمة الهدف هي أحد أعضاء java.lang.annotation.ElementType enum:

  1. ANNOTATION_TYPE. يمكن استخدام نوع التعليق التوضيحي للتعليق على إعلان نوع التعليق التوضيحي.
  2. البناء. يمكن استخدام نوع التعليق التوضيحي للتعليق على إعلان المُنشئ.
  3. حقل. يمكن استخدام نوع التعليق التوضيحي للتعليق على إعلان الحقل.
  4. متغير محلي. يمكن استخدام نوع التعليق التوضيحي للتعليق على إعلان المتغير المحلي.
  5. طريقة. يمكن استخدام نوع التعليق التوضيحي للتعليق على إعلان الطريقة.
  6. صفقة. يمكن استخدام نوع التعليق التوضيحي للتعليق على تصريحات الحزمة.
  7. معامل. يمكن استخدام نوع التعليق التوضيحي للتعليق على إعلانات المعلمات.
  8. اكتب. يمكن استخدام نوع التعليق التوضيحي للتعليق على تعريفات النوع.
1
2
3
4
@ Target ( value = METHOD )
You can have multiple values in the Target annotation .
 
@ Target ( value = { TYPE , FIELD , METHOD , PARAMETER , CONSTRUCTOR , LOCAL_VARIABLE } )

7) @ الشرح الموروث:

تمامًا كما يبدو الاسم ، يتم @Inherited نوع التعليق التوضيحي @ الموروث بواسطة فئات فرعية من النوع المشروح.

1
2
3
4
5
6
7
8
9
10
@ Inherited
@ interface ForEveryone { }
 
@ interface JustForMe { }
 
@ ForEveryone
@ JustForMe
class Superclass { }
 
class Subclass extends Superclass { }

في هذا المثال ، تم إضافة تعليق توضيحي صريح @ForEveryone Superclass @JustForMe . لم يتم تمييز Subclass بشكل صريح بأي منهما ؛ ومع ذلك ، فإنه يرث @ForEveryone لأنه تم التعليق على الأخير بـ @Inherited .

@JustForMe غير مذكور ، لذا فهو غير موروث بواسطة Subclass .

هنا التعليقات التوضيحية على مستوى الفصل

التعليقات التوضيحية على مستوى الفصل