توابع مثال در Go چیست؟

اسناد و تست کد خود را در یک مرحله آسان با توابع مثال بهبود بخشید.

نکات کلیدی

• توابع مثال در Go، قطعه کد قابل آزمایش هستند که به عنوان مستند عمل می کنند و می توانند برای تأیید صحت استفاده شوند.
• توابع نمونه از یک قرارداد نامگذاری پیروی می کنند و می توانند برای بسته ها، توابع، انواع و متدها تعریف شوند.
• توابع نمونه تست های اجرایی هستند و می توانند برای اطمینان از کد قابل اعتماد و به روز نگه داشتن اسناد استفاده شوند.

یکی از نقاط قوت Go، تعداد زیادی از ویژگی‌های تست داخلی و مستندسازی آن است. در این میان ابزار بسیار مفیدی به نام “توابع مثال” است که می تواند به شما کمک کند کد خود را بررسی کرده و آن را برای دیگران توضیح دهید.

به عنوان یک توسعه دهنده Go، باید دقیقاً بدانید که توابع نمونه چیست و چگونه می توانید از آنها برای ساختن نرم افزار قابل نگهداری استفاده کنید.

توابع نمونه چیست؟

توابع نمونه (یا نمونه‌ها) در Golang قطعه‌های کد قابل آزمایشی هستند که می‌توانید به عنوان مستند به یک بسته اضافه کنید و صحت آن را تأیید کنید. توابع نمونه پارامترها را نمی گیرند و نتیجه ای نیز بر نمی گردند.

تصور کنید تابع Multiply زیر را در پروژه خود دارید:

func Multiply(a, b int) int {
    return a * b
}

یک تابع مثال برای Multiply به شکل زیر خواهد بود:

func ExampleMultiply() {
    fmt.Println(Multiply(4, 5))
    // Output: 2
}

توابع نمونه از یک قرارداد نامگذاری مشابه برای آزمایش توابع استفاده می کنند. با اضافه کردن نام تابع به عنوان پسوند به “Example”، یک مثال تابع را تعریف کنید، همانطور که در ExampleMultiply در اینجا وجود دارد.

نگاهی دقیق تر به نمونه توابع

کد در بخش قبل ساختار اصلی یک تابع مثال را نشان می دهد. چیزی که یک مثال را می سازد نام، بدنه تابع و یک نظر خروجی اختیاری در انتهای تابع است.

وقتی کامنت خروجی را اضافه می کنید، Go مثال را کامپایل و اجرا می کند تا صحت آن را تأیید کند، اما بدون نظر، Go فقط تابع نمونه را کامپایل می کند، آن را اجرا نمی کند.

شما می توانید یک مثال برای یک بسته، یک تابع، یک نوع و یک متد بر روی یک نوع تعریف کنید.

تعریف مثال برای موجودیت های مختلف نیاز به رویکردهای متفاوتی دارد.

1. برای تعریف یک مثال برای یک بسته، کافیست تابع خود را Example()، بدون هیچ پسوندی فراخوانی کنید. به عنوان مثال، در اینجا یک مثال در سطح بسته آورده شده است: func Example() {    fmt.Println(“Hello, world!”)    // خروجی:    // Hello, world!}
2. برای تعریف یک مثال برای یک تابع، کافی است نام تابع را همانطور که قبلا یاد گرفتید به عنوان پسوند اضافه کنید. func ExampleMultiply() {    fmt.Println(Multiply(4,5))    // خروجی: 2}
3. برای تعریف یک مثال برای یک نوع، نام را به عنوان پسوند به Example اضافه کنید. یک مثال در اینجا آمده است: ساختار MyStruct را تایپ کنید {    // …}func ExampleMyStruct() {    // …}
4. و در آخر، برای یک متد روی یک نوع خاص، نام نوع، زیرخط و سپس نام متد را اضافه می‌کنید. این یک نمایش است: func (m *MyStruct) MyMethod() {    // …}func ExampleMyStruct_MyMethod() {    // …}

func Example() {
    fmt.Println("Hello, world!")
    // Output:
    // Hello, world!
}

func ExampleMultiply() {
    fmt.Println(Multiply(4,5))
    // Output: 2
}

type MyStruct struct {
    // ...
}

func ExampleMyStruct() {
    // ...
}

func (m *MyStruct) MyMethod() {
    // ...
}

func ExampleMyStruct_MyMethod() {
    // ...
}

شما می توانید چندین مثال برای یک موجودیت با اضافه کردن یک زیرخط اضافی و پسوندی که با یک حرف کوچک شروع می شود، تعریف کنید. به عنوان مثال، ExampleMultiply_second، ExampleMyStruct_MyMethod_second.

شما همچنین می توانید یک مثال بزرگتر برای توضیح منطق پیچیده با استفاده از یک مثال فایل کامل داشته باشید.

یک مثال کامل فایل، فایلی است که به _test.go ختم می‌شود و دقیقاً حاوی یک تابع مثال، بدون تست یا توابع معیار، و حداقل یک اعلان دیگر در سطح بسته است. هنگام نمایش چنین نمونه هایی، godoc کل فایل را نشان می دهد. – وبلاگ go dev

موتور Go عملکردهای مثال شما را بر اساس نحوه تعریف شما تشخیص می دهد و مدیریت می کند.

می‌توانید از گزینه Unordered output برای نظرات خروجی استفاده کنید. این به ویژه در سناریوهایی مفید است که تابع شما لیستی را برمی گرداند که به ترتیب خاصی انتظار نمی رود.

مستندسازی کد خود با توابع مثال

توابع مثال برای اهداف مستندسازی و آزمایشی مفید هستند. یک تابع مثال معمولاً در توضیح رفتار بهتر از نظرات کار می کند.

درست مانند Javadoc جاوا، ابزار مستندسازی داخلی Go، godoc، به کدنویسی اسناد کمک می کند. اما شما می خواهید برخی از کتابخانه ها و عملکردها را با هم مستند کنید تا درک کامل تری از نحوه کار آنها ارائه دهید. مثال‌ها این عقب‌نشینی را از بین می‌برند زیرا می‌توانند تعاملات بین واحدهای مختلف یک بسته را نشان دهند.

ابزار godoc به طور خودکار نمونه ها را با توابع، انواع و بسته هایی که به آنها تعلق دارند مرتبط می کند، بسته به مشخصات شما. همچنین با اجازه دادن به آزمایش در رابط وب اسناد، یک قدم فراتر می رود.

می‌توانید یک بسته یا روش را مستقیماً از مستندات قبل از استفاده از آن در کد خود امتحان کنید.

این تصویر نمونه ای از تابع json.Valid را در زیر encoding/json نشان می دهد:

استفاده از توابع مثال برای تست واحد

توابع مثال برو نیز تست های اجرایی هستند. هنگامی که فرمان go test را اجرا می کنید، موتور هر تابع مثال را با یک نظر خروجی نهایی اجرا می کند و اطمینان حاصل می کند که خروجی آن با آنچه در نظر است مطابقت دارد.

این قابلیت از بسیاری جهات مفید است. این می تواند به عنوان یک لایه اضافی از آزمایش برای اطمینان از کد قابل اعتماد عمل کند، همچنین به شما کمک می کند اسناد خود را با تغییر کدتان پیگیری کنید.

به عنوان مثال، اگر تغییری ایجاد کنید که بر نحوه اجرای یک تابع خاص و نتیجه آن تأثیر می گذارد. اگر نظر خروجی در مثال را برای مطابقت با تغییرات جدید به‌روزرسانی نکنید، آزمایش‌های آن مثال با شکست مواجه می‌شوند.

این کمک زیادی به جلوگیری از قدیمی بودن اسناد می کند، زیرا اسناد شما همیشه با کد به روز خواهند بود.

توابع نمونه کد و مستندات قابل اعتماد تولید می کند

مستندسازی بخش ضروری توسعه نرم افزار است، اما تعداد کمی از زبان ها چنین پلتفرم قدرتمندی را برای مستندسازی و آزمایش کد به شما می دهند.

Go همراه با همه چیزهایی است که برای ایجاد مستندات با کیفیت برای نرم افزار خود نیاز دارید، و توابع نمونه بخش مهمی از آن هستند. از مثال‌هایی استفاده کنید تا به کاربران و همکاران کمک کنید کد شما را سریع‌تر بپذیرند و درک کنند.

منبع مقاله