تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية
أنشئ تعليقات توضيحية مخصصة باستخدام @interface، وعرّف عناصر ذات قيم افتراضية، وطبّق التعليقات التوضيحية الفوقية
تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية درس مجاني في Java Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Java Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Java Academy 4 دروس في المجموع.
ما التعليقات التوضيحية؟
التعليقات التوضيحية هي بيانات وصفية تُطبَّق على الفئات أو الدوال أو الحقول أو المعلمات. وهي لا تغيّر السلوك مباشرةً، بل توفّر معلومات للمترجمات أو الأطر أو المعالجات وقت التشغيل.
تعريف تعليق توضيحي باستخدام @interface
استخدم @interface لتعريف تعليق توضيحي مخصص. تبدو العناصر كأنها دوال. تُحدَّد القيمة الافتراضية باستخدام default.
@interface Retry {
int times() default 3;
long delayMs() default 1000L;
Class<? extends Throwable>[] on() default {Exception.class};
}تطبيق التعليق التوضيحي
طبّق التعليق التوضيحي على الهدف. احذف العناصر التي لها قيم افتراضية. عندما يكون اسم العنصر الوحيد هو value، يمكن تعيينه دون كتابة المفتاح.
@Retry(times = 5, delayMs = 500)
public void callExternalService() { ... }
// Single-element shorthand:
@interface Label { String value(); }
@Label("production")
public class App {}أنواع عناصر التعليقات التوضيحية
يمكن أن تكون العناصر من الأنواع التالية فقط: الأنواع البدائية (int وlong وغيرهما)، أو String، أو Class، أو enum، أو نوع تعليق توضيحي آخر، أو مصفوفة أحادية البعد من أيٍّ مما سبق.
@interface Config {
String host();
int port() default 8080;
LogLevel level() default LogLevel.INFO; // enum
Class<?> handler() default DefaultHandler.class;
String[] tags() default {};
}التعليقات التوضيحية الفوقية: @Retention
يتحكم @Retention في مدة الاحتفاظ بالتعليق التوضيحي: SOURCE (يتخلص منه المترجم)، وCLASS (يُحفظ في ملف .class ولا يكون متاحًا وقت التشغيل)، وRUNTIME (يمكن قراءته عبر الانعكاس).
@Retention(RetentionPolicy.RUNTIME)
@interface Retry {
int times() default 3;
}التعليقات التوضيحية الفوقية: @Target
يقيّد @Target المواضع التي يمكن تطبيق التعليق التوضيحي فيها. ويمكن إدراج أهداف متعددة.
@Target({ElementType.METHOD, ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@interface Audited {
String description() default "";
}@Documented و@Inherited
يُدرج @Documented التعليق التوضيحي في Javadoc. ويسمح @Inherited للفئات الفرعية بأن ترث التعليق التوضيحي من الفئة الفائقة (وذلك للتعليقات التوضيحية على مستوى الفئة فقط).
@Documented
@Inherited
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
@interface Category {
String value();
}التعليقات التوضيحية القابلة للتكرار: @Repeatable
ضع @Repeatable على التعليق التوضيحي للسماح بظهوره عدة مرات على العنصر نفسه. وقدّم تعليقًا توضيحيًا حاويًا يحتوي على مصفوفة.
@Repeatable(Tags.class)
@interface Tag { String value(); }
@interface Tags { Tag[] value(); }
@Tag("fast")
@Tag("stable")
public class Service {}القيم الافتراضية وحذف العناصر
لا يلزم تحديد العناصر التي لها قيم default عند موضع الاستدعاء. أما العناصر التي لا تملك قيمًا افتراضية فهي إلزامية.
@Retry // uses defaults: times=3, delayMs=1000
public void action1() {}
@Retry(times=1) // overrides only times; delayMs stays 1000
public void action2() {}التعليق التوضيحي مقابل الواجهة المعلِّمة
تُفحَص الواجهات المعلِّمة (مثل Serializable) باستخدام instanceof، وتنقل معلومات عن النوع. أما التعليقات التوضيحية فهي أكثر مرونة؛ إذ تحمل بيانات وصفية ويمكن أن تحتوي على عناصر.
التعليقات التوضيحية المضمّنة الشائعة
تعرّف على تعليقات JDK التوضيحية: @Override و@Deprecated و@FunctionalInterface و@SuppressWarnings و@SafeVarargs.
@Override
public String toString() { return "User{" + name + "}"; }
@Deprecated(since = "2.0", forRemoval = true)
public void oldMethod() {}تحقق سريع
ما سياسة الاحتفاظ الوحيدة التي تجعل التعليق التوضيحي قابلًا للقراءة وقت التشغيل؟
مراجعة
عرّف التعليقات التوضيحية باستخدام @interface. استخدم @Retention(RUNTIME) للمعالجة بالانعكاس، و@Target لتقييد الاستخدام، وdefault للعناصر الاختيارية. ويسمح @Repeatable بتكديس التعليقات التوضيحية.
الأسئلة الشائعة
هل درس «تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية» مجاني؟
نعم — نص درس «تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Java Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Java Academy 4 دروس في المجموع.
ماذا ستتعلم في «تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية»؟
أنشئ تعليقات توضيحية مخصصة باستخدام @interface، وعرّف عناصر ذات قيم افتراضية، وطبّق التعليقات التوضيحية الفوقية تتمرن على Java Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.
هل أحتاج إلى خبرة سابقة لأبدأ Java Academy؟
لا تُشترط خبرة سابقة. Java Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.
كم من الوقت يستغرق درس «تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية»؟
معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.
هل يمكنني كتابة وتشغيل أكواد في درس Java Academy هذا؟
نعم. كل درس في Java Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.
جميع الدروس في هذه الدورة
- تعريف التعليقات التوضيحية: العناصر والقيم الافتراضية
- سياسات الاحتفاظ وأنواع الأهداف
- معالجة التعليقات التوضيحية أثناء التشغيل
- معالجات التعليقات التوضيحية أثناء الترجمة