تعليقات C++: السطر الواحد // والمتعددة الأسطر /* */

ما الغرض من التعليقات

التعليق هو نص في الشيفرة المصدرية يتجاهله مترجم C++ تمامًا. فهو لا يصل أبدًا إلى البرنامج المترجَم - إنه موجود فقط من أجل البشر الذين يقرؤون الكود. تستخدم التعليقات لشرح لماذا يُنفَّذ شيء ما بطريقة معينة، أو لترك تذكيرات، أو لتعطيل الكود مؤقتًا دون حذفه.

بالبناء على بنية C++ التي تعرفها بالفعل، التعليقات من الأشياء القليلة التي يمكنك وضعها في أي مكان تقريبًا وسيتخطّاها المترجم ببساطة. وفي C++ نوعان: السطر الواحد (//) والتعليقات الكتلية المتعددة الأسطر (/* */).

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

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

#include <iostream>
using namespace std;

int main() {
    // اطبع تحية في الطرفية
    cout << "Hello, C++!" << endl;

    int score = 90; // يمكن أن يأتي التعليق أيضًا بعد الكود
    cout << score << endl;
    return 0;
}

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

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

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

#include <iostream>
using namespace std;

int main() {
    /*
     * يعرض هذا البرنامج تعليقًا كتليًا.
     * النجمات في بداية كل سطر هي مجرد
     * اصطلاح لتحسين القراءة - وليست مطلوبة.
     */
    cout << "Block comments are handy." << endl;
    return 0;
}

محارف * المحاذاة على الحافة هي اصطلاح في الأسلوب، وليست قاعدة. الجزآن الوحيدان اللذان يهمّان فعلًا هما /* الافتتاحي و*/ الختامي. ويمكن أن يقع التعليق الكتلي حتى في منتصف سطر - فـ int x = 5 /* width */ + 2; صحيح - رغم أن ذلك يصبح صعب القراءة بسرعة.

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

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

#include <iostream>
using namespace std;

int main() {
    cout << "This line runs." << endl;

    // cout << "This line is disabled." << endl;

    /*
    cout << "So is this one," << endl;
    cout << "and this one too." << endl;
    */

    cout << "This line runs as well." << endl;
    return 0;
}

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

فخّ عدم التداخل

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

/*  Trying to disable a region that already has a block comment...
    int n = 10; /* the width */
    cout << n;
*/  // the first */ above already closed the comment - this line is now stray code

ينتهي التعليق الخارجي عند */ الذي يلي the width، لذا لم يعد الباقي معلَّقًا ويتعثّر المترجم عند */ الأخير. عندما تحتاج إلى تعطيل منطقة تحتوي بالفعل على تعليقات كتلية، استخدم // في كل سطر بدلًا من ذلك. تقوم معظم المحرّرات بتبديل تعليقات الأسطر عبر التحديد بالكامل باختصار واحد من لوحة المفاتيح، مما يتجنّب المشكلة تمامًا.

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

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

// Bad: just repeats what the code obviously does
i = i + 1; // add one to i

// Better: explains the reason, which the code can't show
retries++; // back off and retry; the API is rate-limited at 5 req/sec

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

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

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