التعليقات التوضيحية (Annotations)

ما هي الـ Annotation؟

علامة تُضاف للكود لتقدّم معلومات للمترجم أو ل programas الأدوات — لا تغيّر سلوك البرنامج مباشرة.

@Override
public String toString() {
  return "كائن";
}

أشهر العلامات المدمجة

@Override

تؤكد أن الدالة تُعيد تعريف دالة من صنف أعلى. لو كان التوقيع خاطئًا يرفض المترجم البناء:

class Animal {
  void speak() {}
}

class Dog extends Animal {
  @Override
  void speak() {
    System.out.println("ينبح");
  }
}

@Deprecated

تعلن أن العنصر قديم ولا يُنصح باستخدامه:

@Deprecated
void oldMethod() {
  // ...
}

@SuppressWarnings

تُكتم تحذيرات المترجم مؤقتًا:

@SuppressWarnings("unchecked")
List<String> list = (List<String>) new ArrayList();

@FunctionalInterface

تؤكد أن الواجهة تحتوي دالة مجرّدة واحدة فقط:

@FunctionalInterface
interface Processor {
  String process(String input);
}

Processor upper = s -> s.toUpperCase();

تعريف علامة مخصصة

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface LogExecutionTime {
}

الاستخدام:

public class Service {
  @LogExecutionTime
  public void fetchData() {
    // ...
  }
}

علامات التثبيت (Meta-Annotations)

تُستخدم لتعريف العلامات المخصصة:

متى نستخدمها؟

• @app框架: Spring و Hibernate تعتمد بكثافة على العلامات مثل @Autowired و @Entity.
• تحسين الكود: @Override و @FunctionalInterface.
• أتمتة: إنشاء علامات خاصة لتوليد كود أو تسجيل سجلات.

💡 لا تُنشئ علامات مخصصة إلا quando تحتاجها فعلًا — معظم المشاريع تكتفي بالعلامات المدمجة.

🎯 التالي: السجلات (Records).