Kotlin Academy · درس

استخدام Annotations

أضيفوا Annotations إلى الشيفرة

استخدام Annotations درس مجاني في Kotlin Academy على CoddyKit. هذا هو الدرس 1 من أصل 4. يمكنك قراءة الدرس كاملاً أدناه مجاناً — ثم تمرن عليه مباشرة في المتصفح باستخدام محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7. هذا الدرس جزء من مسار التعلم في Kotlin Academy، وتقدمك يتزامن عبر الويب وتطبيق CoddyKit. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ما التعليقات التوضيحية؟

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

تكتبون التعليق التوضيحي باستخدام @ متبوعًا باسمه، وتضعونه مباشرة قبل العنصر الذي ينطبق عليه.

أول تعليق توضيحي

تتضمن المكتبة القياسية عدة تعليقات توضيحية مفيدة. ويحدد @Deprecated الشيفرة التي ينبغي عدم استخدامها بعد الآن، ويعرض تحذيرًا في موضع الاستدعاء.

@Deprecated("Use newGreet() instead")
fun greet() = "Hi"

fun newGreet() = "Hello"

fun main() {
    println(newGreet())
}

التعليقات التوضيحية مع الوسائط

يمكن أن تأخذ التعليقات التوضيحية وسائط تُكتب كما تُكتب معاملات الباني. يقبل @Deprecated رسالة وتلميحًا اختياريًا من نوع ReplaceWith.

@Deprecated(
    message = "Renamed for clarity",
    replaceWith = ReplaceWith("sum(a, b)")
)
fun add(a: Int, b: Int) = a + b

fun sum(a: Int, b: Int) = a + b

fun main() {
    println(sum(2, 3))
}

كتم التحذيرات

يخبر @Suppress المترجم بإسكات تحذيرات محددة للعنصر الذي وُضع عليه التعليق التوضيحي. وتمررون أسماء التحذيرات كسلاسل نصية.

@Suppress("UNUSED_VARIABLE")
fun main() {
    val unused = 42
    println("Runs without the unused-variable warning")
}

JvmStatic وما شابهها

تؤثر بعض التعليقات التوضيحية في طريقة ترجمة Kotlin إلى JVM. تتحكم @JvmStatic و@JvmField و@JvmName في الرمز الثنائي، بحيث يرى مستدعو Java واجهات برمجية أسهل استخدامًا.

لا تأثير لهذه التعليقات في تعليمات Kotlin البرمجية الخالصة، لكنها مهمة للتشغيل البيني.

class Math {
    companion object {
        @JvmStatic
        fun square(x: Int) = x * x
    }
}

fun main() {
    println(Math.square(5))
}

أهداف موضع استخدام التعليقات التوضيحية

يمكن أن تُنشئ الخاصية عدة عناصر في JVM: حقلًا، ودالة getter، ودالة setter، ومعاملات مُنشئ. تحدد أهداف موضع الاستخدام المكان الذي ينبغي أن تُضاف إليه التعليمة التوضيحية.

البنية: @get: و@set: و@field: و@param:.

class User(@get:JvmName("fetchName") val name: String)

fun main() {
    val u = User("Ada")
    println(u.name)
}

Throws من أجل التشغيل البيني مع Java

لا تحتوي Kotlin على استثناءات مفحوصة، لذلك لا يرى مستدعو Java عبارات throws إلا إذا أضفت @Throws. فهي تسجل نوع الاستثناء في توقيع الرمز الثنائي.

import java.io.IOException

@Throws(IOException::class)
fun readData(): String {
    return "data"
}

fun main() {
    println(readData())
}

تعليقات توضيحية متعددة

يمكنك تكديس عدة تعليقات توضيحية على عنصر واحد. ضع كل واحدة في سطر مستقل، أو افصل بينها بمسافات. لا يهم الترتيب.

@Deprecated("old")
@Suppress("DEPRECATION")
fun legacy() = "still here"

fun main() {
    println(legacy())
}

التعليقات التوضيحية على التعبيرات

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

fun main() {
    @Suppress("UNUSED_VARIABLE")
    val temp = computeOnce()
    println("Done")
}

fun computeOnce() = 99

OptIn وواجهات برمجة التطبيقات التجريبية

تضع المكتبات علامات على واجهات برمجة التطبيقات غير المستقرة باستخدام تعليقات توضيحية مخصصة للموافقة على الاستخدام. ولاستخدامها، تقر بالمخاطر عبر @OptIn(SomeApi::class) أو تنقل التعليمة التوضيحية إلى موضع آخر.

وهذا يجعل الميزات التجريبية صريحة بدلًا من أن تُستخدم عرضًا.

fun main() {
    // @OptIn would appear here when calling an experimental function
    println("Opt-in keeps unstable APIs visible")
}

لماذا نستخدم التعليقات التوضيحية؟

تتيح لك التعليقات التوضيحية إيصال القصد إلى الأدوات: إذ تحذر المترجمات من الاستدعاءات المهملة، وتربط مكتبات التسلسل الحقول، وتعثر أطر الاختبار على دوال الاختبار، وتوصل أطر حقن الاعتماديات الاعتماديات ببعضها.

بيانات وصفية وليست منطقًا
تُقرأ في وقت الترجمة أو وقت التشغيل
تبقي الإعداد قريبًا من التعليمات البرمجية

تحقق سريع

اختبر مدى فهمك لاستخدام التعليقات التوضيحية.

مراجعة

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

@Deprecated و@Suppress و@Throws
التشغيل البيني مع JVM: @JvmStatic و@JvmName
أهداف موضع الاستخدام مثل @get: و@field:
الموافقة على استخدام واجهات برمجة التطبيقات التجريبية

ستعرّف تعليقاتك التوضيحية الخاصة في الدرس التالي.

الأسئلة الشائعة

هل درس «استخدام Annotations» مجاني؟

نعم — نص درس «استخدام Annotations» كامل متاح مجاناً هنا على الويب. لتمرينه بشكل تفاعلي (محرر أكواد مدمج ومدرس ذكاء اصطناعي متاح 24/7) وفتح باقي دورة Kotlin Academy، انتقل إلى CoddyKit PRO. تتضمن دورة Kotlin Academy 4 دروس في المجموع.

ماذا ستتعلم في «استخدام Annotations»؟

أضيفوا Annotations إلى الشيفرة تتمرن على Kotlin Academy مع أكواد عملية تشغلها مباشرة في المتصفح، ومدرس ذكاء اصطناعي متاح 24/7 يجيب على أسئلتك أثناء عملك.

هل أحتاج إلى خبرة سابقة لأبدأ Kotlin Academy؟

لا تُشترط خبرة سابقة. Kotlin Academy على CoddyKit منظم للمبتدئين حتى المتقدمين، لذا يمكنك البدء من هنا أو من البداية والتقدم بسرعتك الخاصة. هذا هو الدرس 1 من أصل 4.

كم من الوقت يستغرق درس «استخدام Annotations»؟

معظم دروس CoddyKit تستغرق حوالي 5–10 دقائق. كل منها موجز وتفاعلي، لذا تحرز تقدماً مستمراً وتستأنف من حيث توقفت عبر الويب والتطبيق.

هل يمكنني كتابة وتشغيل أكواد في درس Kotlin Academy هذا؟

نعم. كل درس في Kotlin Academy يتضمن محرر أكواد مدمج، لذا تكتب وتشغل أكواداً حقيقية مباشرة في متصفحك وتحصل على تعليقات فورية من الذكاء الاصطناعي — بدون إعداد محلي.

جميع الدروس في هذه الدورة

← العودة إلى Kotlin Academy