הערות ב-Python: הערות בשורה אחת, בכמה שורות ו-Docstrings

הערות נועדו לבני אדם

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

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

הערות בשורה אחת עם #

הצורה הבסיסית היא # ואחריו ההערה שלכם:

# Calculate the tax portion of the total.
total = 100
tax = total * 0.08
print(tax)

אפשר גם להוסיף הערה קצרה בסוף שורה. לפי המוסכמה, השאירו לפחות שני רווחים לפני ה-#:

refresh_interval = 300  # seconds; keep in sync with the dashboard config
print(refresh_interval)

Python קוראת # בכל מקום מחוץ למחרוזת ומתייחסת לשאר השורה כהערה. החלק של "מחוץ למחרוזת" חשוב: # בתוך מירכאות הוא סתם תו.

url = "https://example.com/#section-2"  # the real comment starts here
print(url)

ה-#section-2 שבתוך המחרוזת הוא חלק מה-URL. Python עוברת למצב "הערה" רק ב-# שאחרי סגירת המחרוזת.

הפיכת כמה שורות להערה

ל-Python אין הערת בלוק מסוג /* */. כדי לדלג על כמה שורות, שימו # בתחילת כל אחת:

# This is a block comment.
# It spans several lines.
# Each line starts with its own #.
print("only this line actually runs")

כמעט אף פעם לא מקלידים את ה-# האלה ידנית. בכל עורך סביר יש קיצור "הפעלה/כיבוי של הערת שורה" שמוסיף או מסיר # בכל שורה מסומנת:

• VS Code: Cmd + / (macOS) או Ctrl + / (Windows/Linux)
• PyCharm: Cmd + / או Ctrl + /
• Vim: תלוי בתוספים שלכם. vim-commentary מקצה את gcc לשורה בודדת ואת gc לבחירה.

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

הטריק של מחרוזת במירכאות משולשות (ולמה זו לא הערה אמיתית)

לפעמים תראו קוד כזה:

"""
This block looks like a comment
but it's actually a string literal
that nothing uses.
"""
print("hi")

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

Docstrings: המקום היחיד שבו מירכאות משולשות שייכות

docstring היא מחרוזת במירכאות משולשות שמוצבת כפקודה הראשונה ממש בפונקציה, במחלקה או במודול. Python מזהה אותה כתיעוד ומנגישה אותה בזמן ריצה דרך הפונקציה help() וה-attribute __doc__:

def discount(price, percent):
    """Return the final price after applying a percentage discount.

    price is a number; percent is between 0 and 100.
    """
    return price * (1 - percent / 100)

print(discount(50, 20))
help(discount)

שני דברים הופכים docstrings לנחמדות:

1. כלים כמו סביבות פיתוח, help() ומחוללי תיעוד קוראים אותן אוטומטית. הערה מעל הפונקציה לא מקבלת שום דבר כזה.
2. הן מתארות את הפונקציה במקום הקריאה: כשמישהו מרחף מעל discount(...) בעורך, ה-docstring קופצת כ-tooltip.

יש מוסכמה (PEP 257) למה שנכנס ל-docstring: סיכום בשורה אחת בשורה הראשונה, שורה ריקה, ואחר כך תיאור ארוך יותר אם צריך. אל תילחצו מהפורמט המדויק ביום הראשון: שורה אחת פשוטה עדיפה בהרבה על היעדר docstring.

מה הערות טובות באמת אומרות

כמה הנחיות שחוסכות הרבה עוגמת נפש בהמשך:

• העדיפו לתאר למה ולא מה. # Loop over the users הוא רעש. # Retry on 503 - Redis sometimes dies mid-deploy הוא זהב.
• עדכנו הערות כשמשנים את הקוד. הערה שגויה גרועה יותר מהיעדר הערה. הערות מיושנות מטעות באופן פעיל את הקוראים הבאים.
• אל תהפכו קוד להערה ותשאירו אותו שם. אם אתם לא צריכים אותו, מחקו אותו. מערכת ניהול הגרסאות זוכרת. קובץ מפוזר בבלוקים שהפכו להערות מאבד אמינות מהר.
• דלגו על המובן מאליו. x = x + 1 # increment x לא מוסיף כלום.

השורה התחתונה

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

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