التعليقات في

نبذة عن التعليقات

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

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

تؤدي التعليقات أغراضًا مختلفة حسب موضع ظهورها.

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

تشرح تعليقات الكود سبب القيام بشيء ما، لا ما تم القيام به. استخدمها عندما لا يكون السبب وراء قرار ما واضحًا من الكود:

results = results[1:] // skipping the header row

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

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

تُستخدم تعليقات التوثيق لتوثيق حزمة أو متغير أو دالة. هذا التوثيق موجّه إلى المبرمجين الآخرين الذين يريدون معرفة كيفية استخدام الكود. ينبغي أن يشرح، على مستوى عام، ما الذي يفعله الكود وكيفية استخدامه. وينبغي ألا يتضمن تفاصيل عن كيفية عمل الكود نفسه. تأتي تعليقات التوثيق مباشرة قبل التعريف، دون سطر فارغ يفصل التعليق عن التعريف. ويحلّلها godoc لتوليد توثيق الحزمة، كما يظهر على pkg.go.dev. ينبغي أن يكون تعليق التوثيق جملة كاملة تبدأ باسم المعرّف وتنتهي بنقطة.

تظهر تعليقات التوثيق على المعرّفات المصدّرة (تلك التي تبدأ بحرف كبير) في التوثيق المُولَّد. أما تعليقات التوثيق على المعرّفات غير المصدّرة (تلك التي لا تبدأ بحرف كبير) فلن تظهر، لكنها قد تظل توفّر سياقًا مفيدًا داخل الكود.

تبدأ التعليقات التي توثّق الحزم باسم الحزمة وتصف ما تفعله الحزمة:

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

تبدأ التعليقات التي توثّق الدوال باسم الدالة وتصف ما تفعله الدالة، بما في ذلك وسائطها وقيم الإرجاع:

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

تبدأ التعليقات التي توثّق المتغيرات باسم المتغير وتصف ما يمثّله المتغير:

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

للاطلاع على المواصفة الكاملة لتعليقات التوثيق، راجع دليل توثيق Go.