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

لماذا التوثيق ليس واجباً مملاً بل قوة خارقة للمطور

تخيل أنك تفتح مشروع JavaScript لشخص آخر (أو مشروعك الخاص الذي كتبته منذ ثلاثة أشهر). الملفات مليئة بالدوال السهمية، و async/await، وتفكيك الكائنات. لكن لماذا تسمى هذه الدالة transformData؟ ماذا تستقبل؟ والأهم — لماذا هي موجودة أصلاً بجانب processArray؟

إذا سبق لك أن وجدت نفسك تفكر: "لا أتذكر ماذا يحدث هنا"، فهذه المقالة لك. توثيق JavaScript ليس فقرات نصية مملة. إنه احترام لذاتك المستقبلية ولزملائك في العمل. إنه سرعة الدخول إلى المشروع وتقليل عدد الأخطاء. في هذه المقالة، سنستعرض أفضل ممارسات توثيق كود JS: من JSDoc إلى توليد توثيق كامل.

توثيق كود JavaScript: فلسفة "الكود الناطق"

قبل كتابة التعليقات، من المهم أن تفهم: أفضل تعليق هو ذلك الذي لا تحتاجه. الكود المثالي يجب أن يشرح نفسه بنفسه. كيف تحقق ذلك؟

تسمية المتغيرات والدوال

مثال سيء:

// سيء\nconst x = 10; // ما هو x؟\nfunction d(a, b) { return a * b; } // ماذا تفعل d؟\n

مثال جيد:

// جيد\nconst MAX_RETRY_COUNT = 10;\nfunction calculateDiscountedPrice(price, discountPercent) {\n  return price * (1 - discountPercent / 100);\n}\n

استخدم أسماء كاملة وذات معنى. سمِّ الدوال بأفعال (getUser، validateEmail)، والمتغيرات بأسماء (userList، isActive). هذا هو أساس الكود ذاتي التوثيق.

متى نحتاج التعليقات فعلاً

\n
• منطق الأعمال المعقد: مثلاً حساب الضرائب بصيغة غير واضحة.
\n
• حل مؤقت أو اختراق: ضع علامة TODO أو FIXME.
\n
• سبب اختيار هذا النهج: كانت هناك بدائل، لكن هذا هو الأمثل من حيث السرعة.
\n
• وصف الواجهة العامة (API): حتى يعرف المطورون الآخرون كيفية استدعاء الدالة.
\n

JSDoc: معيار توثيق JavaScript

JSDoc هو صيغة لكتابة التوثيق مباشرة في الكود، تفهمها المحررات (VS Code، WebStorm) وأدوات التوليد. إنه أمر لا غنى عنه لأي مشروع جاد.

التعليق الأساسي للدالة

/**\n * يحسب التكلفة النهائية للطلب مع الخصم والضريبة.\n * @param {number} price - السعر الأساسي للمنتج.\n * @param {number} discount - الخصم بالنسبة المئوية (0-100).\n * @param {number} taxRate - نسبة الضريبة (0-100).\n * @returns {number} التكلفة النهائية.\n */\nfunction calculateTotal(price, discount, taxRate) {\n  const discountedPrice = price * (1 - discount / 100);\n  return discountedPrice * (1 + taxRate / 100);\n}\n

الآن عند التمرير فوق الدالة calculateTotal في المحرر، سترى وصفها ومعاملاتها وقيمة الإرجاع. سحر!

التعليقات للكائنات والأنواع

/**\n * @typedef {Object} User\n * @property {number} id - المعرف الفريد.\n * @property {string} name - اسم المستخدم.\n * @property {boolean} isActive - هل الحساب نشط.\n */\n\n/**\n * يحصل على قائمة المستخدمين النشطين.\n * @param {User[]} users - مصفوفة المستخدمين.\n * @returns {User[]} المصفوفة المصفاة.\n */\nfunction getActiveUsers(users) {\n  return users.filter(user => user.isActive);\n}\n

استخدام @typedef يتيح لك إنشاء أنواع مخصصة، مما يجعل الكود مقروءاً وآمناً. هذا مفيد بشكل خاص في المشاريع التي لا تستخدم TypeScript.

توثيق الدوال غير المتزامنة

/**\n * يحمل بيانات المستخدم من الخادم.\n * @async\n * @param {number} userId - معرف المستخدم.\n * @returns {Promise