توثيق كود Kotlin: كتابة كود يشرح نفسه بنفسه

التوثيق في مشاريع Kotlin: فن أن تكون مفهومًا

تخيل: تفتح مشروع Kotlin لشخص آخر. الكود جميل ومختصر، لكن... لا تفهم ما الغرض من هذه الدالة وماذا تُرجع. هل هذا مألوف؟ والآن تخيل أن هذا المشروع هو مشروعك الخاص، ولكن بعد ستة أشهر. التوثيق في Kotlin ليس مجرد مجاملة للزملاء. إنه استثمار في مستقبل كودك.

في هذه المقالة، سنستعرض أفضل ممارسات توثيق مشاريع Kotlin. ستتعلم كيفية استخدام KDoc وDokka والتعليقات العادية بحيث يتحدث كودك عن نفسه. هيا بنا!

لماذا التوثيق في Kotlin ليس مملًا؟

Kotlin هي لغة صُممت للبشر. تُقرأ مثل اللغة الإنجليزية، وتركيبها يخلصك من الكود المتكرر. ولكن حتى أكثر الأكواد أناقة يمكن أن تكون لغزًا بدون توثيق. خاصة عندما يتعلق الأمر بـ:

\n
• منطق الأعمال المعقد؛
\n
• المكتبات وواجهات برمجة التطبيقات (API) التي يستخدمها مطورون آخرون؛
\n
• مشاريع Android ذات دورة حياة طويلة؛
\n
• الحلول المؤسسية حيث تغيير الموظفين أمر طبيعي.
\n

التوثيق الجيد لـ Kotlin يحل ثلاث مهام: يشرح "ماذا" يفعل الكود، "لماذا" يفعله، و"كيف" تستخدمه. بدونه، تخاطر بالحصول على كود لا يريد أحد لمسه (حتى أنت بنفسك).

KDoc: الأداة الرئيسية لتوثيق Kotlin

KDoc هو نظير JavaDoc لـ Kotlin. يستخدم تعليقات من النوع /** ... */ ويدعم Markdown. هذا هو المعيار الفعلي للتوثيق في مشاريع Kotlin.

إليك مثال أساسي:

/**\n * يحسب الخصم للمستخدم بناءً على حالته.\n *\n * @param price السعر الأصلي للمنتج.\n * @param userLevel مستوى المستخدم (BRONZE, SILVER, GOLD).\n * @return السعر النهائي بعد الخصم.\n * @throws IllegalArgumentException إذا كان price سالبًا.\n */\nfun calculateDiscount(price: Double, userLevel: UserLevel): Double {\n    // المنطق\n}

لاحظ: يستخدم KDoc الوسوم @param و@return و@throws. ولكن على عكس JavaDoc، يمكنك كتابة Markdown مباشرة داخل التعليق. هذا مناسب للقوائم والروابط والتنسيق.

أفضل ممارسات KDoc

\n
• اكتب للبشر، وليس للآلات. لا تكرر ما هو واضح من الكود. بدلاً من // يحدد القيمة اكتب // يحدد القيمة التي ستستخدم عند حساب الضرائب.
\n
• وثق واجهة برمجة التطبيقات العامة (public API). الدوال الداخلية (private أو internal) يمكن توثيقها باختصار أو عدم توثيقها على الإطلاق.
\n
• استخدم @see و @sample. أشر إلى الدوال ذات الصلة أو أمثلة الاستخدام.
\n
• لا تنسَ @receiver لدوال الإضافة (extension functions).
\n

Dokka: تحويل التعليقات إلى توثيق جميل

Dokka هو مولد توثيق لـ Kotlin. يمكنه إنشاء HTML وMarkdown وJavaDoc وحتى توثيق للمشاريع متعددة المنصات. إذا كنت تكتب مكتبة أو تعمل ضمن فريق، فإن Dokka هو أفضل صديق لك.

التثبيت بسيط. في ملف build.gradle.kts، أضف الإضافة (plugin):

plugins {\n    id("org.jetbrains.dokka") version "1.9.20"\n}

ثم قم بتشغيل الأمر:

./gradlew dokkaHtml

سينشئ Dokka مجلد build/dokka/html مع توثيق جميل يتضمن جميع تعليقات KDoc الخاصة بك، وتسلسل الفئات، وحتى روابط للمصادر.

نصائح حول Dokka

\n
• قم بتعيين الشعار ووصف المشروع في dokkaConfiguration؛
\n
• استخدم @suppress لإخفاء العناصر غير المرغوب فيها