כשאתה חושב על תכנות, זה טבעי להתמקד בנושאים כמו שפות, אלגוריתמים וניפוי באגים. אבל תיעוד טכני יכול להיות חשוב באותה מידה.
ללא תיעוד טוב, השימוש החוזר בקוד עלול להיפגע. משתמשים חדשים בבסיס קוד יכולים בקלות ללכת לאיבוד או מתוסכלים אם התיעוד אינו עדין. זה לא רק חשוב להבין מה תוכנית עושה, אלא איך - או אפילו למה - היא עושה את זה.
חבילות כמו Pydoc עבור Python ו-Javadoc עבור Java עוזרות על ידי אוטומציה של חלק מהתהליך. הכלי Godoc עושה בדיוק את אותו הדבר עבור Go.
מה זה גודוק?
Godoc היא חבילת Go המאפשרת לך ליצור, לנהל ולהשתמש בתיעוד Go ב"דרך ה-Go". דרך ה-Go היא אוסף של עקרונות שכמתכנתי Go, עליך לפעול לפיהם כדי לשפר את איכות הקוד.
באמצעות Godoc, אתה יכול לקרוא בקלות תיעוד וקוד של מפתחים אחרים. אתה יכול גם להפוך את יצירת התיעוד שלך לאוטומטי ולפרסם אותו באמצעות Godoc.
גודוק דומה ל Javadoc, מתעד הקוד עבור Java. שניהם משתמשים בהערות ובקוד במודולים כדי ליצור תיעוד. ושני הכלים מבנים את התיעוד הזה ב-HTML כך שתוכל לצפות בו בדפדפן.
תחילת העבודה עם Godoc
השימוש ב-Godoc קל. כדי להתחיל, התקן את חבילת Godoc מאתר golang באמצעות הפקודה הזו:
ללכת קבל golang.org/x/tools/cmd/godoc
הפעלת פקודה זו תתקין את Godoc בסביבת העבודה שציינת. לאחר השלמתו, אתה אמור להיות מסוגל להפעיל את godoc פקודה בטרמינל. אם יש שגיאות כלשהן בהתקנה שלך, נסה לעדכן את Go לגרסה עדכנית.
Godoc מחפש הערות בודדות ומספר שורות לכלול בתיעוד שהיא מייצרת.
הקפד לעצב קוד בדרך Go, כפי שהוסבר ב הפרסום של Effective Go על ידי צוות Go לקבלת התוצאות הטובות ביותר.
הנה דוגמה לשימוש בהערות בשורה אחת בסגנון C++:
// המשתמש הוא מודל struct המכיל
סוּג מִשׁתַמֵשׁ מבנה {
}
אתה יכול גם להשתמש בהערות בלוק בסגנון C:
/*
המשתמש הוא מבנה נתונים מותאם אישיתאתה יכול לכלול כאן כל טקסט ושרת Godoc יעצב אותו כשאתה מפעיל אותו.
*/
סוּג מִשׁתַמֵשׁ מבנה {
}
בהערות למעלה, "משתמש" מתחיל את המשפטים מכיוון שההערה מתארת מה עושה מבנה המשתמש. זהו אחד מהנושאים הרבים שבהם דנה דרך Go. התחלת משפטי תיעוד בשם שימושי היא קריטית מכיוון שהמשפט הראשון מופיע ברשימת החבילות.
הפעלת שרת Godoc
לאחר שהערת את הקוד שלך, תוכל להפעיל את godoc הפקודה בטרמינל שלך, מספריית הקוד של הפרויקט שלך.
באופן קונבנציונלי, מפתחי Go משתמשים בפורט 6060 לארח תיעוד. זו הפקודה להפעלת שרת Godoc ביציאה זו:
godoc -http=:6060
הפקודה למעלה מארחת את תיעוד הקוד שלך localhost, או 127.0.0.1. היציאה לא חייבת 6060; godoc יפעל על כל נמל פנוי. עם זאת, תמיד עדיף לעקוב אחר מוסכמות התיעוד של Go.
לאחר הפעלת הפקודה, תוכל להציג את התיעוד שלך בדפדפן על ידי ביקור מארח מקומי: 6060. הזמן שלוקח לגודוק ליצור את התיעוד שלך יהיה תלוי בגודלו ובמורכבותו.
הקוד שלהלן תואם לדרך Go, במקרה זה באמצעות הערות בשורה אחת.
// שם החבילה
חֲבִילָה מִשׁתַמֵשׁ// fmt אחראי על העיצוב
יְבוּא (
"fmt"
)// המשתמש הוא מבנה של נתונים אנושיים
סוּג מִשׁתַמֵשׁ מבנה {
גיל int
שֵׁם חוּט
}funcרָאשִׁי() {
// אנושי הוא אתחול של מבנה המשתמש
אנושי := משתמש {
גיל: 0,
שם: "אדם",
}fmt. Println (אנושי. דבר())
}
// Talk היא שיטה של מבנה המשתמש
func(משתמש מקלט)דבר()חוּט {
לַחֲזוֹר "כל משתמש יכול להגיד משהו!"
}
אם אתה מריץ את Godoc במודול הקוד שלמעלה, אתה אמור לראות פלט שנראה בערך כך:
שימו לב שזה בפורמט מוכר, בדומה למה שתמצאו באתר התיעוד הרשמי של Go.
Godoc משתמש בהערה שלפני הצהרת החבילה בתור סקירה כללית. ודא שההערה הזו מתארת את מה שהתוכנית שלך עושה.
ה אינדקס מכיל קישורים להצהרות הסוג והשיטות כך שתוכל לנווט אליהם במהירות.
Godoc מספק גם פונקציונליות לצפייה בקוד המקור המרכיב את החבילה ב- קבצי חבילה סָעִיף.
שיפור התיעוד שלך באמצעות Godoc
אתה יכול לכלול יותר מסתם טקסט רגיל בתיעוד ה-Godoc שלך. אתה יכול להוסיף כתובות URL ש-Godoc יפיק קישורים עבורן ולבנות את ההערות שלך לפסקאות.
אם אתה רוצה לקשר למשאב, כתוב את כתובת האתר בתגובה שלך, ו-Godoc יזהה אותו ויוסיף קישור. לפסקאות, השאר שורת הערה ריקה.
// החבילה הראשית
חֲבִילָה רָאשִׁי// מסמך מייצג מסמך רגיל.
//
// קישור ל https://google.com
סוּג מסמך מבנה {
דפים int
הפניות חוּט
חתם bool
}// Write כותב מסמך חדש לאחסון
//
// אתה יכול ללמוד על כתיבה מ-Wikipedia.com
funcלִכתוֹב() {
}
שימו לב ש-Godoc דורש מכם לכתוב כתובות URL במלואן כדי שיקשר אותן. בדוגמה זו, כתובת האתר של Google כוללת את https:// קידומת, אז Godoc מוסיף קישור אליו. מכיוון שדומיין ויקיפדיה אינו כתובת URL מלאה בפני עצמה, גודוק ישאיר אותו בשקט.
להלן כמה עקרונות טובים ליישום בעת תיעוד קוד ה-Go שלך:
- שמור על התיעוד שלך פשוט ותמציתי.
- התחל את המשפט של פונקציות, טיפוסים והצהרות משתנים לפי שמם.
- התחל שורה עם הזחה כדי לעצב אותה מראש כקוד.
- הערות שמתחילות "BUG(שם)" כמו "BUG(joe): זה לא עובד" הן מיוחדות. Godoc יזהה אותם בתור באגים וידווח עליהם בחלק משלהם בתיעוד.
גודוק יכול להקל על צרות התיעוד שלך
באמצעות Godoc, אתה יכול להיות פרודוקטיבי יותר ולדאוג פחות מהמאמץ של תיעוד התוכניות שלך ביד.
עליך לשמור על התיעוד שלך מדויק, מפורט וענייני כדי להקל על קהל היעד שלך לקרוא ולהבין. זה גם חיוני שתשמור על הערות קוד מעודכנות בזמן שאתה משנה את התוכנית שלך.
עיין בתיעוד של חבילת Godoc כדי ללמוד עוד על השימוש ב-Godoc.
