כיצד לתעד קוד Python באמצעות Docstrings

ללא תיעוד מתאים, זה יכול להיות קשה להבין, לתחזק ולתקן באגים בקוד שלך. ב-Python, אתה יכול להשתמש ב-docstrings כדי לספק תיאורים תמציתיים ודוגמאות כיצד הקוד עובד.

מה הם דוקטרינגים?

מחרוזות Docstrings הן מחרוזות שאתה יכול להוסיף לקוד Python שלך כדי להסביר מה הוא עושה וכיצד להשתמש בו. פיסת הקוד יכולה להיות א פונקציית Python, מודול או מחלקה.

מחרוזות Docstrings נראות הרבה כמו הערות Python סטנדרטיות, אבל יש להן כמה הבדלים. הערות Python מספקות מידע נוסף למפתחים על פעולתו הפנימית של הקוד, כגון פרטי יישום או אזהרות שיש לזכור בעת הרחבת הקוד.

מצד שני, מחרוזות docstrings מספקות בעיקר מידע למשתמשי הקוד שאולי לא בהכרח צריכים לדעת את פרטי היישום שלו אלא צריכים להבין מה הוא עושה וכיצד להשתמש בו.

איך לכתוב מחרוזות דוק

בדרך כלל אתה כולל מחרוזות docstrings בתחילת גוש הקוד שאתה רוצה לתעד. עליך לצרף אותם במרכאות משולשות (). אתה יכול לכתוב מחרוזות docstrings של שורה אחת או docstrings מרובות שורות.

מחרוזות docstrings בשורה אחת מתאימות לקוד פשוט שאינו דורש תיעוד רב.

להלן דוגמה לפונקציה הנקראת כפל. המחרוזת מסבירה את פונקציית הכפל לוקחת שני מספרים, מכפילה אותם ומחזירה את התוצאה.

defלְהַכפִּיל(א, ב):
מכפיל שני מספרים ומחזיר את התוצאה
לַחֲזוֹר א * ב

השתמש במחרוזות docstrings מרובות שורות לקוד מורכב יותר הדורש תיעוד מפורט.

שקול את מחלקת המכוניות הבאה:

מעמדאוטו:

 א מעמדמייצגיםאאוטולְהִתְנַגֵד.
 תכונות:
 קילומטראז' (צף): הקילומטראז' הנוכחי של המכונית.
 שיטות:
 נסיעה (מיילים): מסיע את המכונית ל מספר הקילומטרים שצוין.

def__init__(עצמי, קילומטראז'):
 self.mileage = קילומטראז'
defנהיגה(עצמי, מיילים):

 נוהג במכונית ל מספר הקילומטרים שצוין.
 טיעונים:
 מיילים (צף): מספר המיילים שיש לנסוע.
 החזרות:
אף אחד

 self.mileage += מיילים

מחרוזת הדוק של המחלקה שלמעלה מתארת ​​את מה שהמחלקה מייצגת, התכונות שלה והשיטות שלה. בינתיים, מחרוזות ה-docstrings עבור שיטת הכונן מספקות מידע על מה שהשיטה עושה, הארגומנטים שהיא מצפה ומה היא מחזירה.

זה מקל על כל מי שעובד עם הכיתה הזו להבין כיצד להשתמש בה. היתרונות הנוספים של שימוש ב-docstrings כוללים:

• תחזוקה של קוד: על ידי מתן תיאור ברור של אופן פעולת הקוד, מחרוזות docstrings עוזרות למפתחים לשנות ולעדכן את הקוד מבלי להציג שגיאות.
• שיתוף פעולה קל יותר: כאשר מספר מפתחים משתפים פעולה על אותו בסיס קוד - למשל, עם ה כלי שיתוף חי של Visual Studio— מחרוזות doc מאפשרות למפתחים לתעד את הקוד באופן עקבי כך שכולם בצוות יוכלו להבין אותו.
• קריאות קוד משופרת: מחרוזות Docstrings מספקות סיכום ברמה גבוהה של מה שהקוד עושה ומאפשר כל מי שקורא את הקוד כדי להבין במהירות את מטרתו מבלי לעבור על הקוד כולו לַחסוֹם.

פורמטים של Docstring

מחרוזת מסמך טובה צריכה לתאר מה קטע קוד עושה, את הטיעונים שהוא מצפה ופרטי יישום במידת הצורך. זה צריך לכלול במיוחד את כל מקרי הקצה שעל כל מי שמשתמש בקוד להיות מודע אליהם.

לתבנית docstring בסיסית יש את הסעיפים הבאים:

• שורת סיכום: סיכום של שורה אחת של מה שהקוד עושה.
• ארגומנטים: מידע על הארגומנטים שהפונקציה מצפה להם כולל סוגי הנתונים שלהם.
• ערך החזרה: מידע על ערך ההחזרה של הפונקציה כולל סוג הנתונים שלה.
• העלאות (אופציונלי): מידע על חריגים שהפונקציה עשויה להעלות.

זהו רק פורמט בסיסי מכיוון שישנם פורמטים אחרים שאתה יכול לבחור כדי לבסס את מחרוזות הדוקטורט שלך. הפופולריים שבהם הם Epytext, reStructuredText (הידוע גם בשם reST), NumPy ו-Google docstrings. לכל אחד מהפורמטים הללו יש תחביר משלו, כפי שמוצג בדוגמאות הבאות:

אפיטקסט

מחרוזת מסמך העוקבת אחר פורמט ה-Epytext:

defלְהַכפִּיל(א, ב):

 הכפל שני מספרים יחד.
 @param a: המספר הראשון להכפלה.
 @type a: int
 @param b: המספר השני להכפלה.
 @type b: int
 @return: המכפלה של שני המספרים.
 @rtype: int

לַחֲזוֹר א * ב

reStructuredText (reST)

מחרוזת דוקטר העוקבת אחר פורמט reST:

defלְהַכפִּיל(א, ב):

 הכפל שני מספרים יחד.
 :param a: המספר הראשון להכפל.
 :type a: int
 :param b: המספר השני להכפלה.
 :type b: int
 :לַחֲזוֹר: המכפלה של שני המספרים.
 :rtype: int

לַחֲזוֹר א * ב

NumPy

מחרוזת מסמך העוקבת אחר פורמט NumPy:

defלְהַכפִּיל(א, ב):

 הכפל שני מספרים יחד.
 פרמטרים

 a: int
 המספר הראשון להכפיל.
 ב: אינט
 המספר השני להכפלה.
 החזרות

 int
 המכפלה של שני המספרים.

לַחֲזוֹר א * ב

גוגל

מחרוזת מסמכים העוקבת אחר הפורמט של Google:

defלְהַכפִּיל(א, ב):

 הכפל שני מספרים יחד.
 טיעונים:
 a (int): המספר הראשון שיש להכפיל.
 b (int): המספר השני שיש להכפיל.
 החזרות:
 int: המכפלה של שני המספרים.

לַחֲזוֹר א * ב

למרות שכל ארבעת הפורמטים של המחרוזות מספקות תיעוד שימושי עבור פונקציית הכפל, הפורמטים NumPy ו-Google קלים יותר לקריאה מאשר הפורמטים Epytext ו-reST.

כיצד לכלול בדיקות ב-Docstrings

אתה יכול לכלול דוגמאות בדיקה במחרוזות ה-docstrings שלך באמצעות מודול doctest. מודול ה-doctest מחפש במחרוזת ה-doc טקסט שנראה כמו הפעלות אינטראקטיביות של Python ולאחר מכן מבצע אותן כדי לוודא שהן פועלות כמו שצריך.

כדי להשתמש ב-doctests, כלול את הקלט לדוגמה ואת הפלטים הצפויים ב-docstring. להלן דוגמה כיצד תעשה זאת:

defלְהַכפִּיל(א, ב):

 הכפל שני מספרים יחד.
 פרמטרים

 a: int
 המספר הראשון להכפיל.
 ב: אינט
 המספר השני להכפלה.
 החזרות

 int
 המכפלה של שני המספרים.
 דוגמאות

 >>> להכפיל(2, 3)
6
 >>> להכפיל(0, 10)
0
 >>> להכפיל(-1, 5)
-5

לַחֲזוֹר א * ב

ה דוגמאות החלק מכיל שלוש קריאות לפונקציה עם ארגומנטים שונים ומציין את הפלט הצפוי עבור כל אחד מהם. כאשר אתה מפעיל את מודול ה-doctest כפי שמוצג להלן, הוא יבצע את הדוגמאות וישווה את הפלט בפועל לפלט הצפוי.

python -m doctest multiply.py

אם יש הבדלים כלשהם, מודול ה-doctest מדווח עליהם ככשלים. שימוש ב-doctests עם docstrings כמו זה עוזר לך לוודא שהקוד פועל כמצופה. שימו לב שבדיקות דוקטורט אינן תחליף למקיפים יותר בדיקות יחידות ומבחני אינטגרציה עבור קוד Python שלך.

כיצד להפיק תיעוד מ-Docstrings

למדת את היסודות של שימוש במחרוזות docstrings כדי לתעד את קוד Python שלך ואת החשיבות של תיעוד באיכות גבוהה. כדי לתפוס את זה, ייתכן שתרצה ליצור תיעוד עבור המודולים והפונקציות שלך ממחרוזות ה-docstrings שלהם.

אחד ממחוללי התיעוד הפופולריים שבהם אתה יכול להשתמש הוא ספינקס. זה תומך בפורמט reST docstring כברירת מחדל, אבל אתה יכול להגדיר אותו לעבוד עם פורמט Google או NumPy.