מכיוון שאנו כבר יודעים כיצד לכתוב את ההערות הרב-שורות, אנו עשויים להשתמש במרכאות בודדות משולשות או במירכאות כפולות משולשות. אנו משתמשים במחרוזת תיעוד כאשר אנו רוצים לתאר את הפונקציות שלנו כדי שנוכל לקבל את התיעוד כשאנחנו צריכים אותו. חלק מה-IDE נותנים לך תיעוד רק על ידי ריחוף מעל השם וחלק מדגישים מילות מפתח מסוימות. אבל העובדה היא ש-docstrings ב-NumPy גמישים הרבה יותר מאשר בשפות אחרות. Docstring הוא מחרוזת מילולית המופיעה בתחילת הגדרת הפונקציה. עלינו לספק ערכים ספציפיים תוך שימוש במחרוזות הדוק במקרים של פונקציות, מחלקות וכו'.
בעת שימוש במחרוזות docstrings עם פונקציות, עלינו להעביר את הארגומנטים. כאשר משתמשים בהם עם מחלקות, אנו מעבירים את התכונות והשיטות. במקרה של מודולים, עלינו לספק רשימה של מחלקות ופונקציות. במקרה של החבילה, אנו מעבירים את רשימת המודולים עם פונקציונליות. אז בעצם, מטרת ה-docstring היא, כפי שהשם מסביר, שהיא עוזרת בתיעוד של הקוד שלנו. אנחנו עושים תיעוד כדי שאם מישהו ישתמש בקוד שלנו בעתיד, הוא יוכל להבין את הקוד שלנו ואת ההיגיון מאחורי הקוד שלנו בעזרת docstring. לפונקציות מובנות יש גם מחרוזות docstrings; אנו יכולים להשתמש בפונקציה של help() כדי להסתכל על המחרוזת של פונקציות מובנות.
ישנם כמה הבדלים בין הערות ל-docstrings. מתורגמנים מתעלמים מהערות, אך מתורגמנים אינם מתעלמים מ-docstrings. זיכרון מוקצה למחרוזות docstrings. הערה היא תיאור של קוד, אבל מצד שני, מחרוזות דוקציות מספרות לנו את מטרת הקוד.
תחביר:
התחביר לכתיבת מחרוזות ה-docstrings ב-NumPy הוא:
'''הודעת מחרוזת דוק'''
אוֹ
'''הודעת דוקטורט'''
שים לב ש-docstring אינו פונקציה או שיטה, ולכן אין לה תחביר תקין. הדבר היחיד שצריך לשים לב כאן הוא שאנחנו מתחילים את המחרוזת עם שלוש מרכאות בודדות או שלוש מרכאות כפולות. אנו כותבים את התיאור שלנו של הקוד ומסיימים אותו שוב עם שלוש מרכאות בודדות או שלוש מרכאות כפולות בסוף. אין שום דבר חובה לכתוב ל-docstrings. אתה רק צריך לשים שלוש מרכאות בודדות או כפולות לפני ואחרי תיאור המחרוזת שלך.
דוגמה 1:
כדי להבין את המחרוזות בצורה טובה יותר, הבה נבצע דוגמה. בדוגמה זו, לאחר הכללת ספריית NumPy, אנו פשוט מכריזים על המשתנה 'a' ועוד משתנה 'b'. לאחר מכן, אנו יוצרים את המחרוזת שלנו שאומרת 'הבה נוסיף משתנים 'a' ו-'b'. במקרה שלנו, זו דוגמה קלה אבל אם הקוד שלנו מורכב, זה עוזר מאוד לקודד בהבנת הקוד. לאחר מכן, אנו מסכמים את המשתנים 'a' ו-'b' ומאחסנים את תוצאת הפלט שלהם במשתנה אחר שהוא 'c'. לבסוף, נדפיס את הערך של המשתנה 'c'. כעת, אנו מבצעים את הקוד שלנו.
יְבוּא רדום כפי ש לְמָשָׁלא = 1
ב = שתיים
'''בוא נוסיף משתנים a ו-b'''
ג = א+ב
הדפס ( ג )
זה הפלט שלנו מקטע הקוד הנתון. אנו יכולים לראות שהמערכת לא נתנה שום שגיאה לגבי תחביר שגוי או משהו עבור שורה 7 של הקוד שלנו. כמו כן, המערכת לא הדפיסה את המחרוזת שלנו. במקום זאת, הוא הדפיס רק את הפלט של המשתנה 'c' שבו אמרנו למערכת שלנו להדפיס. זה מראה כיצד פועלות ה-docstrings. בפעם הבאה, כשקודן חדש ינסה לעבוד על הקוד שלנו, הוא יבין מה אנחנו עושים בעזרת ה-docstring שלנו. אבל הוא לא יודפס כפלט כך שהמשתמש בקוד לא יפריע לו.
דוגמה 2:
כעת, אנו מבצעים דוגמה מורכבת כדי להבין את פעולת ה-docstring. ראשית, אנו כוללים את ספריית NumPy ולאחר מכן כותבים מחרוזת doc בה אנו מסבירים את שורת הקוד הבאה שבה אנו מסבירים את האתחול של המערך. אנחנו גם מוסיפים את מחרוזות ה-docstrings בחלק השני של הקוד. כעת, אם נשתף את הקוד הזה עם מפתח חדש של Python מבלי להוסיף את מחרוזות ה-docstrings, איכשהו יהיה לו קשה לדעת את העבודה ואת המטרה של הקוד הזה. הוא צריך לחפש תחילה על הפונקציות בהן השתמשנו. אבל אם נוסיף מחרוזת דוק לקוד שלנו, למפתחים אחרים יהיה קל להבין את הקוד מבלי ללמוד יותר על הפונקציות. איננו מוגבלים להוספת הערות לכמה מגבלות; הערות יכולות להיות של שורה אחת או יותר. ניתן גם להוסיף אותו יותר מפעם אחת בקוד. לאחר מכן, ייבא את NumPy בתור np.
'''יצירת המשתנה שאליו נעביר מערך בגודל 1x6'''מַעֲרָך = לְמָשָׁל מַעֲרָך ( [ אחד עשר , 22 , 33 , 44 , 55 , 66 ] )
'''הקצאת המערך לפונקציה tofile() כדי לאפשר לו לשמור בקובץ בשם arr'''
מַעֲרָך . לתייק ( 'arr.bin' )
'''הצג את הקובץ באמצעות הפונקציה fromfile'''
הדפס ( לְמָשָׁל fromfile ( 'arr.bin' , dtype = int ) )
כפי שמוצג בקטע הבא, מחרוזות docstrings אינן מוצגות בפלט, מה שאומר שזה לא משפיע על הפלט או הקומפילציה של הקוד. מתעלמים מחרוזות מסמכים במהלך תהליך ההידור.
סיכום
במדריך זה, למדנו על מחרוזות docstrings ב-NumPy. השווינו את המחרוזות עם הערות והסברנו את ההבדל בין שניהם. למדנו את התחביר של docstrings וכיצד לכתוב את docstrings בקוד שלנו. יתרה מזאת, ניסינו גם להסביר מה הם ה-docstrings ב-NumPy וכיצד הם פועלים בעזרת דוגמאות. לבסוף, ציינו שהם חיוניים עבור קודנים. לא נחזור על החשיבות של docstrings ב-NumPy. רק נגיד שאתה צריך להשתמש במחרוזות הדוק בקוד שלך. ב-NumPy, סגנון הכתיבה של מחרוזות docstrings הוא הפופולרי ביותר. זה נמצא בשימוש נרחב בקהילת התכנות כדי ליידע אחד את השני על העבודה והפונקציונליות של הקודים שלהם. מדריך זה יעזור לך להתחיל עם NumPy docstrings. ניסינו לכסות את רוב מה שתצטרך באמצעות מחרוזות ה-docstrings ב-NumPy.