كتابة التعليقات في لغة جو Go

التعليقات هي عبارات دخيلة على الشيفرات البرمجية وليست جزءًا منها، إذ يتجاهلها المُصرّف compiler والمُفسّر interpreter، كما يُسهِّل تضمين التعليقات في الشيفرات من قراءتها وفهمها ومعرفة وظيفة كل جزء من أجزائها، لأنها توفر معلومات وشروحات حول ما يفعله كل جزء من البرنامج.

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

صياغة التعليقات

تبدأ التعليقات بالمحرفَين //وتنتهي بنهاية السطر الحالي، وغالبًا ما نضع فراغًا بعد هذين المحرفين لجعل التعليق مُرتبًا أكثر مثل:

// This is a comment
// هذا تعليق على الشيفرة

تُتجاهل التعليقات كما ذكرنا أي وكأنها غير موجودة، وبالتالي عند تشغيل البرنامج لن يطرأ أي حدث يُشير إلى وجودها، فالتعليقات ضمن التعليمات البرمجية مُخصصة ليقرأها البشر وليس للحاسب، ففي برنامج "Hello، World!‎" مثلًا يمكنك إضافة التعليقات كما يلي:

package main

import (
    "fmt"
)

func main() {
    // ‫اطبع العبارة "Hello, World!‎" إلى الطرفية
    fmt.Println("Hello, World!")
}

مثال آخر لوضع التعليقات ضمن حلقة for التي تُكرِّر تنفيذ كتلة برمجية أو مجموعة من التعليمات البرمجية:

package main

import (
    "fmt"
)

func main() {
    // عرف المتغير التالي على أنه شريحة من سلاسل نصية
    sharks := []string{"hammerhead", "great white", "dogfish", "frilled", "bullhead", "requiem"}

    // حلقة تكرار للمرور على كل عنصر من عناصر القائمة وطباعته
    for _, shark := range sharks {
        fmt.Println(shark)
    }
}

نستنتج من المثالين السابقين أن التعليقات يجب أن تكون على سويّة التعليمات التي توضحها، أي بالمسافة البادئة نفسها للشيفرة التي تُعلّق عليها، وبالتالي يجب أن يكون تعليق بدون مسافة بادئة تسبُقه من أجل تعريف دالة بدون مسافة بادئة، وكل مقطع برمجي مسبوق بمسافة بادئة سيكون له تعليقات تتماشى مع هذه المسافة.

لاحظ على سبيل المثال كيف سنُعلّق على الدالة main، ولاحظ كيف سنضع التعليقات بما يتماشى مع كل مقطع مسبوق بمسافة بادئة:

package main

import "fmt"

const favColor string = "blue"

func main() {
    var guess string
    // إنشاء حلقة تكرار
    for {
        // اطلب من المستخدم تخمين لوني المفضل
        fmt.Println("Guess my favorite color:")
        // اقرأ ما أدخله المستخدم واطبع النتيجة
        if _, err := fmt.Scanln(&guess); err != nil {
            fmt.Printf("%s\n", err)
            return
        }
        // تأكد إن خمن اللون الصحيح
        if favColor == guess {
            // اللون الذي أدخله صحيح
            fmt.Printf("%q is my favorite color!\n", favColor)
            return
        }
        // اللون الذي أدخله خطأ ونطلب منه تكرار الإجابة
        fmt.Printf("Sorry, %q is not my favorite color. Guess again.\n", guess)
    }
}

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

يجب أن يكون التعليق على شيفرة ما هو توضيح لمضمونها أو للفكرة التي أنتجت هذه الشيفرة وليس كتابة أسئلة أو شيء آخر، أي يجب أن تُجيب التعليقات عن السبب الذي أنتج الشيفرة.

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

يمكن استخدام التعليقات الكتليّة Block Comments -أي عدة أسطر من التعليقات- لتوضيح الشيفرات البرمجية المعقدة التي تتوقع بأن لا يكون القارئ على دراية بها، إذ تنطبق هذه التعليقات الطويلة على جزء من الشيفرة أو جميعها، كما توضع في نفس مستوى المسافة البادئة للشيفرة، كما يمكن كتابة التعليقات الكتلية بطريقتين؛ الأولى من خلال المحرفَين السابقَين // وتكرارهما من أجل كل سطر مثل:

// First line of a block comment
// Second line of a block comment

أما الطريقة الثانية، فمن خلال علامة الفتح */ التي نضعها في بداية التعليق وعلامة الإغلاق */ التي نضعها في نهاية التعليق، إذ يُستخدَم // عادةً مع عمليات التوثيق؛ أما /* ... */ لتصحيح الأخطاء debugging.

/*
تعليق طويل
يمتد على
أكثر من سطر
*/

سنستخدم التعليقات الكتليّة في المثال التالي لتوضيح الدالة ()MustGet:

// ‫تأخذ الدالة MustGet رابطًا وتعيد الصفحة الرئيسية له
// وإن حصل أي خطأ ستظهره
func MustGet(url string) string {
    resp, err := http.Get(url)
    if err != nil {
        panic(err)
    }

    defer resp.Body.Close()
    var body []byte
    if body, err = ioutil.ReadAll(resp.Body); err != nil {
        panic(err)
    }
    return string(body)
}

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

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

التعليقات السطرية

توضَع التعليقات السطرية Inline comments على السطر نفسه الذي توجد فيه التعليمة البرمجية، وهي مثل التعليقات الأخرى أي تبدأ بالمحرفَين `// ومسافة بيضاء واحدة، إذ تبدو التعليقات الضمنيّة عمومًا كما يلي:

[code]  // تعليق سطري يشرح سطر الشيفرة

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

z := x % 2  // ‫ احصل على باقي قسمة العدد x

يمكن أيضًا استخدام التعليقات السطرية لشرح السبب وراء فعل شيء ما أو لتعطي بعض المعلومات الإضافية كما في المثال التالي:

x := 8  // إسناد قيمة للعدد

يجب استخدام التعليقات السطرية عند الضرورة وعندما توفِّر إرشادات مفيدةً للشخص الذي يقرأ البرنامج.

تعليق جزء من الشيفرة بدواعي الاختبار والتنقيح

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

يمكن أن يتيح لك استخدام الرمزين /*...*/ تجربة بدائل أخرى أثناء إعداد الشيفرة أو للتعليق على التعليمات البرمجية التي تفشل أثناء استمرار العمل على أجزاء أخرى من التعليمات البرمجية الخاصة بك.

// دالة تضيف عددين
func addTwoNumbers(x, y int) int {
    sum := x + y
    return sum
}

// دالة تضرب عددين
func multiplyTwoNumbers(x, y int) int {
    product := x * y
    return product
}

func main() {
    /*
        ‫علقنا في هذا المقال استدعاء الدالة addTwoNumbers
        لأنه يولد خطأ لم نكتشفه فلا نريد إيقاف الشيفرة

        a := addTwoNumbers(3, 5)
        fmt.Println(a)

    */

    m := multiplyTwoNumbers(5, 9)
    fmt.Println(m)
}

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

خاتمة

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

سيسمح لك التعليق الصحيح على الشيفرة في جو باستخدام الأداة Godoc، وهي أداة تستخرِج التعليقات من التعليمات البرمجية الخاصة بك وتُنشئ وثائق لبرنامج جو الخاص بك.

ترجمة -وبتصرُّف- للمقال How To Write Comments in Go لصاحبه Gopher Guides.