أساسيات جافا

التعليقات وJavadoc

15 دقيقة الدرس 8 من 14

التعليقات وJavadoc

تُكتب الشيفرة مرةً واحدة لكنها تُقرأ مرات كثيرة — من قِبَلك في المستقبل، ومن قِبَل زملائك، ومن قِبَل الأدوات المختلفة. التعليقات وJavadoc هما الطريقة الأساسية التي يتواصل بها مطوّرو Java لنقل النوايا داخل ملفات المصدر. في هذا الدرس ستتعلم كل أسلوب تعليق تدعمه Java، ومتى تستخدم كل أسلوب، وكيف تكتب توثيق API احترافيًا باستخدام وسوم Javadoc.

تعليقات السطر الواحد

يبدأ تعليق السطر الواحد بـ // ويمتد حتى نهاية السطر. استخدمه لشرح تعليمة واحدة أو ترك ملاحظة قصيرة.

int speed = 60; // كيلومترات في الساعة، وليس ميلات

// اضرب في 1000 للتحويل من كيلومترات إلى أمتار
double distanceMetres = speed * 1000.0;

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

تعليقات الكتلة

يفتح تعليق الكتلة بـ /* ويُغلق بـ */. كل شيء بين هذين المحددين يتجاهله المُصرِّف بصرف النظر عن عدد الأسطر.

/*
  هذه الدالة تحوّل درجة الحرارة من مئوية إلى فهرنهايت.
  المعادلة: F = (C * 9/5) + 32
  المدخل يجب أن يكون double صالحًا؛ لا يُجرى أي فحص للحدود.
*/
double toFahrenheit(double celsius) {
    return (celsius * 9.0 / 5.0) + 32.0;
}

تعليقات الكتلة رائعة لتعطيل الكود مؤقتًا أثناء تصحيح الأخطاء. لُفَّ القسم بـ /* ... */، اختبر، ثم احذف التعليق. لكن احذر من ترك كود مُعلَّق في الإنتاج — نظام إدارة الإصدارات هو المكان المناسب للكود القديم.

تعليقات Javadoc

تبدأ تعليقات Javadoc بـ /** (نجمتان) وتُغلق بـ */. تُوضع مباشرةً فوق تعريف صنف أو واجهة أو مُنشئ أو دالة أو حقل. تقرأ أداة javadoc هذه التعليقات وتُنتج توثيقًا بصيغة HTML — نفس HTML الذي تراه في الموقع الرسمي لـ Java API على docs.oracle.com.

/**
 * يمثّل حسابًا مصرفيًا يدعم الإيداع والسحب.
 *
 * @author  Edrees Salih
 * @version 1.0
 * @since   17
 */
public class BankAccount {

    /** الرصيد الحالي؛ دائمًا >= 0. */
    private double balance;

    /**
     * يُنشئ حسابًا جديدًا برصيد افتتاحي محدد.
     *
     * @param initialBalance  الرصيد الابتدائي؛ يجب أن يكون >= 0
     * @throws IllegalArgumentException إذا كان {@code initialBalance} سالبًا
     */
    public BankAccount(double initialBalance) {
        if (initialBalance < 0) {
            throw new IllegalArgumentException("Balance cannot be negative.");
        }
        this.balance = initialBalance;
    }

    /**
     * يودع المبلغ المحدد في الحساب.
     *
     * @param  amount  المبلغ المراد إيداعه؛ يجب أن يكون > 0
     * @return الرصيد الجديد بعد الإيداع
     * @throws IllegalArgumentException إذا لم يكن {@code amount} موجبًا
     */
    public double deposit(double amount) {
        if (amount <= 0) {
            throw new IllegalArgumentException("Deposit amount must be positive.");
        }
        balance += amount;
        return balance;
    }
}

وسوم Javadoc الشائعة

تظهر الوسوم دائمًا داخل كتلة /** ... */ وتبدأ بـ @. أهمها:

@param name description — يوثّق معاملًا واحدًا للدالة.
@return description — يصف القيمة المُعادة (احذفه للدوال من نوع void).
@throws ExceptionType description — يوثّق الاستثناء الذي قد تُطلقه الدالة.
@author name — يسجّل اسم المؤلف (على مستوى الصنف فقط).
@version text — يسجّل رقم الإصدار (على مستوى الصنف فقط).
@since text — يشير إلى إصدار Java أو المنتج الذي أُضيفت فيه هذه الواجهة.
{@code expression} — وسم مضمَّن؛ يعرض المحتوى بخط أحادي العرض دون معالجة HTML.
{@link ClassName#method} — يُنشئ رابطًا تشعبيًا في HTML المُنتَج للتنقل إلى الصنف أو الدالة المشار إليها.

Javadoc مخصص لواجهة API العامة. نادرًا ما تحتاج الحقول الخاصة والمساعدات داخلية إلى Javadoc — فهي تفاصيل تنفيذية. خصص Javadoc للأعضاء public وprotected التي سيستدعيها مطوّرون آخرون.

كتابة كود يوثّق نفسه

أفضل تعليق في أغلب الأحيان هو عدم كتابة تعليق — لأن الكود نفسه واضح بما يكفي. يعتمد الكود الموثِّق لنفسه على أسماء ذات معنى، ودوال صغيرة محددة الغرض، وثوابت مختارة بعناية، حتى يفهم القارئ النية دون الحاجة للتوقف عند تعليق.

// صعب القراءة — يحتاج تعليقًا لفهم الرقم السحري
if (statusCode == 3) { // 3 تعني "تم الشحن"
    notifyCustomer();
}

// يوثّق نفسه — لا يحتاج تعليقًا
final int SHIPPED = 3;
if (statusCode == SHIPPED) {
    notifyCustomer();
}

بالمثل، دالة باسم calculateMonthlyInterest(double principal, double annualRate) تخبرك بكل شيء دون تعليق. أما دالة باسم calc(double a, double b) فتجبرك على قراءة جسمها.

تجنب التعليقات الزائدة. التعليق الذي يُعيد صياغة الكود فحسب يضيف ضوضاء ويتحوّل إلى عبء صيانة — يجب تحديثه في كل مرة يتغير فيها الكود. اكتب تعليقات تشرح لماذا، وليس ماذا.

توليد توثيق HTML

شغّل أمر javadoc من الطرفية لتحويل تعليقاتك إلى موقع قابل للتصفح:

javadoc -d docs src/BankAccount.java

الراية -d docs تحدد مجلد الإخراج. افتح docs/index.html في المتصفح لرؤية توثيقك المُنسَّق. كذلك تعرض بيئات التطوير المتكاملة كـ IntelliJ IDEA تعليقات Javadoc مباشرةً في التلميحات أثناء الكتابة.

الخلاصة

استخدم // للملاحظات القصيرة، و/* ... */ للشرح متعدد الأسطر أو تعطيل الكود مؤقتًا، و/** ... */ لتوثيق Javadoc لجميع أعضاء الـ API العامة. استثمر في أسماء وصفية حتى تقرأ شيفرتك كالنثر، واحتفظ بالتعليقات لشرح لماذا اتُخذ قرار ما — لا لوصف ما يفعله الكود. التوثيق الجيد علامة من علامات احتراف التطوير بلغة Java.