اسناد مفیدی را برای پروژه های Go خود به طور خودکار از نظرات کد خود ایجاد کنید.
وقتی به برنامه نویسی فکر می کنید، طبیعی است که روی موضوعاتی مانند زبان ها، الگوریتم ها و اشکال زدایی تمرکز کنید. اما مستندات فنی می تواند به همان اندازه برای درست کردن اهمیت داشته باشد.
بدون مستندات خوب، قابلیت استفاده مجدد کد ممکن است آسیب ببیند. کاربرانی که تازه وارد پایگاه کد شده‌اند، می‌توانند به راحتی گم شوند یا ناامید شوند، اگر مستندات کامل نباشد. درک اینکه یک برنامه چه کاری انجام می دهد نه تنها مهم است، بلکه مهم است که چگونه – یا حتی چرا – آن را انجام می دهد.
بسته‌هایی مانند Pydoc برای Python و Javadoc برای Java با خودکار کردن بخشی از فرآیند کمک می‌کنند. ابزار Godoc دقیقاً همین کار را برای Go انجام می دهد.
گودوک چیست؟
Godoc یک بسته Go است که به شما امکان می دهد اسناد Go را در “راه Go” ایجاد، مدیریت و استفاده کنید. Go way مجموعه ای از اصول است که به عنوان یک برنامه نویس Go باید برای بهبود کیفیت کد از آنها پیروی کنید.
با استفاده از Godoc، می توانید به راحتی اسناد و کد توسعه دهندگان دیگر را بخوانید. همچنین می‌توانید ایجاد مستندات خود را خودکار کرده و با استفاده از Godoc منتشر کنید.
Godoc شبیه به Javadoc، مستندساز کد جاوا است. آنها هر دو از نظرات و کد در ماژول ها برای تولید اسناد استفاده می کنند. و هر دو ابزار این اسناد را در HTML ساختار می دهند تا بتوانید آن را در مرورگر مشاهده کنید.
شروع با Godoc
استفاده از Godoc آسان است. برای شروع، بسته Godoc را از وب سایت golang با استفاده از این دستور نصب کنید:
go get golang.org/x/tools/cmd/godoc
اجرای این دستور Godoc را در فضای کاری مشخص شده شما نصب می کند. پس از تکمیل، باید بتوانید دستور godoc را در ترمینال اجرا کنید. اگر در نصب شما خطایی وجود دارد، Go را به نسخه اخیر به روز کنید.
چگونه کد خود را نظر دهید
گودک به دنبال نظرات تک خطی و چند خطی می‌گردد تا در مستنداتی که ایجاد می‌کند بگنجاند.
همانطور که در نشریه Effective Go توسط تیم Go برای بهترین نتایج توضیح داده شده است، مطمئن شوید که کد Go way را قالب بندی کنید.
در اینجا یک مثال با استفاده از نظرات تک خطی به سبک C++ آورده شده است:
// User is a struct model containing
type User struct {
}
همچنین می توانید از نظرات بلوک به سبک C استفاده کنید:
/*
User is a custom data structure
You can include any text here and the Godoc server will format it when you run it.
*/
type User struct {
}
در نظرات بالا، “کاربر” جملات را شروع می کند زیرا نظر توضیح می دهد که ساختار کاربر چه می کند. این یکی از موضوعات متعددی است که Go way به آن پرداخته است. شروع جملات مستندات با نام مفید بسیار مهم است زیرا اولین جمله در لیست بسته ظاهر می شود.
اجرای یک سرور Godoc
هنگامی که کد خود را نظر دادید، می توانید دستور godoc را در ترمینال خود از دایرکتوری کد پروژه خود اجرا کنید.
به طور معمول، توسعه دهندگان Go از پورت 6060 برای میزبانی اسناد استفاده می کنند. این دستور برای اجرای یک سرور Godoc در آن پورت است:
godoc -http=:6060
دستور بالا میزبان اسناد کد شما در لوکال هاست یا 127.0.0.1 است. پورت نباید 6060 باشد. godoc روی هر پورت خالی اجرا می شود. با این حال، همیشه بهتر است از قراردادهای اسناد Go پیروی کنید.
پس از اجرای دستور، می توانید با مراجعه به localhost:6060 اسناد خود را در مرورگر مشاهده کنید. مدت زمانی که Godoc برای تولید اسناد شما صرف می کند به اندازه و پیچیدگی آن بستگی دارد.
یک برنامه نمونه با نظرات Godoc
کد زیر به Go way پایبند است، در این مورد از نظرات تک خطی استفاده می شود.
// name of the package
package user
// fmt is responsible for formatting
import (
"fmt"
)
// User is a struct of human data
type User struct {
Age int
Name string
}
func main() {
// human is an initialization of the User struct
human := User {
Age: 0,
Name: "person",
}
fmt.Println(human.Talk())
}
// Talk is a method of the User struct
func (receiver User) Talk() string {
return "Every User Gets to Say Something!"
}
اگر Godoc را بر روی ماژول کد بالا اجرا کنید، باید خروجی چیزی شبیه به این را ببینید:
توجه داشته باشید که در قالبی آشنا است، مشابه آنچه در وب سایت اسناد رسمی Go خواهید دید.
Godoc از نظر قبل از اعلام بسته به عنوان نمای کلی استفاده می کند. مطمئن شوید که این نظر کار برنامه شما را توصیف می کند.
فهرست شامل پیوندهایی به اعلان‌های نوع و روش‌ها است تا بتوانید به سرعت به آنها پیمایش کنید.
Godoc همچنین عملکردی را برای مشاهده کد منبع تشکیل دهنده بسته در بخش فایل های بسته ارائه می دهد.
بهبود اسناد خود با استفاده از Godoc
شما می‌توانید چیزی بیش از متن ساده را در اسناد Godoc خود بگنجانید. شما می توانید URL هایی را اضافه کنید که Godoc برای آنها پیوند ایجاد می کند و نظرات شما را در پاراگراف ها ساختار می دهد.
اگر می خواهید به منبعی پیوند دهید، URL را در نظر خود بنویسید و Godoc آن را تشخیص داده و یک پیوند اضافه می کند. برای پاراگراف ها، یک خط نظر خالی بگذارید.
// Package main
package main
// Document represents a regular document.
//
// Link to https://google.com
type Document struct {
pages int
references string
signed bool
}
// Write writes a new Document to the storage
//
// You can learn about writing from Wikipedia.com
func Write() {
}
توجه داشته باشید که Godoc از شما می خواهد که URL ها را به طور کامل بنویسید تا بتواند آنها را پیوند دهد. در این مثال، URL گوگل شامل پیشوند https:// است، بنابراین Godoc یک لینک به آن اضافه می کند. از آنجایی که دامنه ویکی پدیا به تنهایی یک URL کامل نیست، گودوک آن را به حال خود رها می کند.
در اینجا برخی از بهترین اصولی که باید هنگام مستندسازی کد Go خود اعمال کنید، آورده شده است:
- مستندات خود را ساده و مختصر نگه دارید.
- جمله توابع، انواع و اعلان متغیرها را با نام آنها شروع کنید.
- یک خط را با یک تورفتگی شروع کنید تا از قبل آن را به عنوان کد قالب بندی کنید.
- نظراتی که با “BUG(name)” شروع می شوند مانند “BUG(joe): این کار نمی کند” خاص هستند. Godoc آنها را به عنوان باگ تشخیص می دهد و آنها را در بخش خود از اسناد گزارش می دهد.
Godoc می تواند مشکلات اسناد شما را کاهش دهد
با استفاده از Godoc، می توانید بهره وری بیشتری داشته باشید و کمتر نگران تلاش برای مستندسازی دستی برنامه های خود باشید.
شما باید مستندات خود را دقیق، دقیق و دقیق نگه دارید تا خواندن و درک آن برای مخاطبان هدف آسان‌تر شود. همچنین ضروری است که نظرات کد را در حین اصلاح برنامه خود به روز نگه دارید.
برای کسب اطلاعات بیشتر در مورد استفاده از Godoc، اسناد بسته Godoc را بررسی کنید.