در تمرین قبلی دیدیم که دو روش برای نوشتن «کامنت» در Go وجود دارد: کامنتهای تکخطی که پیش از آنها // میآید و بلوکهای کامنت چندخطی که با /* و */ احاطه میشوند.
در Go، کامنتها نقش مهمی در مستندسازی کد دارند.
از آنها در دستور godoc استفاده میشود؛ این دستور آن کامنتها را استخراج میکند تا مستندات مربوط به بستههای Go را بسازد.
یک کامنت مستندسازی باید یک جملهی کامل باشد که با اسم آنچه توصیف میشود شروع شود و با نقطه تمام شود.
کامنتها باید پیش از بستهها و همچنین شناسههای صادرشده قرار بگیرند؛ برای مثال توابع صادرشده، متدها، متغیرهای بسته، ثابتها و ساختارها، که در تمرینهای بعدی بیشتر دربارهی آنها یاد خواهید گرفت.
یک متغیر سطح بسته میتواند به این شکل باشد:
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
کامنتهای بسته باید مستقیماً پیش از عبارت بسته (package x) نوشته شوند و مانند زیر با Package x ... شروع شوند:
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
کامنت تابع باید مستقیماً پیش از اعلان تابع نوشته شود.
باید یک جملهی کامل باشد که با اسم تابع شروع شود.
برای مثال، کامنت یک تابع صادرشده به اسم Calculate باید به شکل Calculate ... باشد.
همچنین باید توضیح دهد که تابع چه آرگومانهایی میگیرد، با آنها چه میکند و مقادیر بازگشتیاش چه معنایی دارند و در پایان با نقطه تمام شود):
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
گابلینوکوس کشوری است که پیشبینی آبوهوا را بسیار جدی میگیرد. از آنجا که شما توسعهدهندهای مشهور، مسئولیتپذیر و ماهر هستید، از شما خواستند برنامهای بنویسید که بتواند وضعیت فعلی آبوهوای شهرهای مختلف گابلینوکوس را پیشبینی کند. در آن زمان سرتان شلوغ بود، پس از یکی از دوستانتان خواستید که به جای شما این کار را انجام دهد. پس از مدتی، رئیسجمهور گابلینوکوس با شما تماس گرفت و گفت که کد دوستتان را نمیفهمد. وقتی کد را بررسی میکنید، متوجه میشوید که دوستتان مانند یک برنامهنویس مسئولیتپذیر عمل نکرده و هیچ توضیحی در کد وجود ندارد. خود را موظف میدانید که برنامه را روشن کنید تا گابلینها هم بتوانند آن را بفهمند.
weather
چون گابلینها به باهوشی شما نیستند، فراموش کردهاند که این بسته چه کاری باید برایشان انجام دهد.
لطفاً برای package weather توضیحی بنویسید که محتوای آن را توصیف کند.
توضیح بسته باید بسته را معرفی کند و اطلاعاتی مرتبط با کل بسته ارائه دهد.
CurrentCondition و CurrentLocation
رئیسجمهور گابلینوکوس کمی بدگمان است و میترسد از متغیرهای بدون توضیح برای نابودی کشورش استفاده شود.
لطفاً نحوهی استفاده از متغیرهای بستهی CurrentCondition و CurrentLocation را روشن کنید و خیال رئیسجمهور را راحت کنید.
این توضیح باید به هر کاربر بسته بگوید که این متغیرها چه اطلاعاتی را در خود نگه میدارند و او میتواند با آنها چه کارهایی انجام دهد.
Forecast()
اپراتورهای پیشبینی گابلینوکوس میخواهند بدانند تابع Forecast() چه کاری انجام میدهد (اما به آنها نگویید که چطور این کار را میکند، چون متأسفانه گیجتر میشوند).
لطفاً برای این تابع توضیحی بنویسید که بگوید تابع چه کاری انجام میدهد، نه اینکه چطور آن را انجام میدهد.