تعليقات Java: سطر واحد ومتعددة الأسطر وJavadoc

ما الغاية من التعليقات

التعليق نصٌّ في شيفرتك المصدرية يتجاهله مُترجِم Java تجاهلًا تامًّا. فهو لا يصبح أبدًا جزءًا من البرنامج أثناء تشغيله، بل يوجد حصرًا من أجل البشر الذين يقرؤون الكود. تستخدم التعليقات لتوضيح لماذا أُنجِز شيءٌ ما بطريقة معيّنة، أو لترك تذكيرات، أو لتعطيل الكود مؤقتًا دون حذفه.

في Java ثلاثة أنواع من التعليقات: تعليق السطر الواحد (//)، وتعليقات الكتلة متعددة الأسطر (/* */)، وتعليقات التوثيق Javadoc (/** */). جميعها تؤدي الوظيفة الأساسية نفسها، وهي أن يجري تجاهلها عند الترجمة، لكنك تلجأ إلى كلٍّ منها في مواقف مختلفة.

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

تبدأ الشَّرطتان المائلتان (//) تعليقًا يمتد حتى نهاية السطر الحالي. يتخطّى المُترجِم كلَّ شيء من // حتى انتهاء السطر.

public class Main {
    public static void main(String[] args) {
        // اطبع رسالة ترحيب على الطرفية
        System.out.println("Hello, Java!");

        int score = 90; // يمكن أن يأتي التعليق أيضًا بعد الكود
        System.out.println(score);
    }
}

لاحظ أن التعليق الثاني يتشارك السطر مع كود حقيقي. فكل ما يقع قبل // يظل ينفّذ؛ ولا يُتجاهل سوى الجزء الذي يليه. هذا هو أكثر أساليب التعليق شيوعًا للملاحظات القصيرة.

تعليقات الكتلة متعددة الأسطر

عندما تمتد ملاحظتك على عدة أسطر، يكون تعليق الكتلة أنظف من وضع // في بداية كل سطر. يبدأ تعليق الكتلة بـ /* وينتهي بـ */. وكل ما يقع بينهما، مهما بلغ عدد الأسطر، يجري تجاهله.

public class Main {
    public static void main(String[] args) {
        /*
         * يعرض هذا البرنامج تعليق كتلة.
         * النجمات في بداية كل سطر ليست سوى
         * عُرف لتحسين القراءة، وهي ليست إلزامية.
         */
        System.out.println("Block comments are handy.");
    }
}

محارف * المصطفّة على طول الحافة هي عُرف في الأسلوب لا قاعدة. والجزآن الوحيدان اللذان لهما أهمية فعلية هما /* في البداية و*/ في الخاتمة.

تعطيل الكود بالتعليق

التعليقات هي الطريقة المعتادة لتعطيل الكود أثناء التجريب من دون حذفه. استخدم // لسطر واحد، أو تعليق كتلة لتعطيل عدة أسطر دفعةً واحدة.

public class Main {
    public static void main(String[] args) {
        System.out.println("This line runs.");

        // System.out.println("This line is disabled.");

        /*
        System.out.println("So is this one,");
        System.out.println("and this one too.");
        */

        System.out.println("This line runs as well.");
    }
}

شغّل البرنامج وسترى أن السطرين اللذين يحملان كلمة "runs" فقط هما اللذان يُطبعان. أما استدعاءات println المُعلَّقة فهي غير مرئية للمُترجِم.

مزلق شائع: تعليقات الكتلة لا تتداخل. فأول */ يُغلق التعليق مهما سبقه من /*. لذلك لا يمكنك تضمين كتلة /* ... */ داخل كتلة /* ... */ أخرى؛ إذ تنهي علامة */ الداخلية التعليق بأكمله، فيصير ما تبقّى خطأً في الصياغة. وإن احتجت إلى تعطيل منطقة تحتوي أصلًا على تعليقات كتلة، فاستخدم // في كل سطر (وتقوم معظم المحرّرات بذلك باختصار لوحة مفاتيح واحد).

تعليقات التوثيق Javadoc

يبدو تعليق Javadoc كتعليق كتلة، لكنه يبدأ بـ /**، أي نجمتين. الغرض منه توثيق صنف أو دالة أو حقل، ويوضع مباشرةً فوق العنصر الذي يصفه. تحوّل أداة javadoc هذه التعليقات إلى توثيق HTML قابل للتصفّح لواجهة البرمجة، وتعرضها بيئات التطوير المتكاملة كتلميحات منبثقة عند التمرير.

public class Main {
    /**
     * Returns the larger of two integers.
     *
     * @param a the first number
     * @param b the second number
     * @return whichever of {@code a} and {@code b} is greater
     */
    static int max(int a, int b) {
        return a > b ? a : b;
    }

    public static void main(String[] args) {
        System.out.println(max(3, 9));
    }
}

الوسوم @param و@return و@throws حقول مُنظَّمة تفهمها الأدوات. أما بالنسبة للمُترجِم فهذا لا يزال مجرّد تعليق مُتجاهَل؛ فقيمته كامنة كليًّا في التوثيق الذي يولّده وفي التلميحات التي تقدّمها بيئة التطوير لسائر المطوّرين (ولك أنت نفسك بعد ستة أشهر).

التعليقات الجيدة في مقابل الضجيج

ينبغي أن يوضّح التعليق شيئًا لا يستطيع الكود قوله بنفسه. أما التعليقات التي تكتفي بإعادة صياغة ما يفعله الكود فتضيف فوضى وتميل إلى التقادم مع تغيّر الكود.

// سيئ: يكرّر فقط ما يفعله الكود بوضوح
int i = i + 1; // أضف واحدًا إلى i

// أفضل: يوضّح السبب الذي لا يستطيع الكود إظهاره
retries++; // تراجَع ثم أعد المحاولة؛ فواجهة البرمجة محدودة بـ 5 طلبات في الثانية

اسعَ إلى جعل الكود نفسه سهل القراءة عبر الأسماء الواضحة والبنية الجيدة، واحتفظ بالتعليقات لتوضيح السبب: القصد، والمفاضلات، والحالات الحدّية، وروابط السياق. وإن وجدت نفسك تكتب تعليقًا لشرح سطر مربك، فذلك في الغالب إشارة إلى أن الأجدر هو إعادة تسمية متغيّر أو استخراج دالة بدلًا من ذلك.

التالي: المتغيّرات

والآن بعد أن صرت قادرًا على إضافة الملاحظات إلى كودك، فإن لبنة البناء التالية هي تخزين البيانات فيه. تتناول الصفحة التالية المتغيّرات: كيف تُصرّح عنها، وما الأنواع التي تحملها، والقواعد التي تفرضها Java لأنها لغة ذات تحقّق ساكن من الأنواع.