توضیحات در

درباره‌ی توضیحات

با «کامنت»ها می‌توانید بدون آنکه بر نحوه‌ی اجرای کد تأثیری بگذارید، یادداشت‌هایی در کد بگذارید. یک کامنت تک‌خطی در هر جایی از یک خط با // شروع می‌شود. کامپایلر هر چیزی را از // تا پایان آن خط نادیده می‌گیرد. وقتی کامنتی در همان خط بعد از کد می‌آید، اغلب به آن «کامنت درون‌خطی» می‌گویند. کامنت چندخطی در هر جایی از یک خط با /* شروع می‌شود و با */ پایان می‌یابد. کامپایلر هر چیزی را که در میان این دو قرار دارد، در یک یا چند خط، نادیده می‌گیرد.

// 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 را ببینید.