פייתון/פייתון גרסה 2/הערות

הערות בשפה אנושית (לרוב אנגלית) בקוד יכולות לשפר את בהירותו.

הערות שורה

הערות בפייתון מתחילות בתו # וממשיכות עד סוף השורה

# This is a comment.

המתרגם מתעלם מקטעים אלו, והם משמשים להסברת הקוד בלבד.

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

השימוש בהערות

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

# This line prints 'Hello, world!' to the screen.
print 'Hello, world!'

תיעוד פונקציות ומחלקות

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

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

תיעוד פונקציה

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

def S(r):
	'''This function returns the area of\na circle with radius r.'''
	return 3.14*r*r

כעת ניתן לגשת לתיעוד זה באמצעות כתיבת:

>>> S.__doc__
'This function returns the area of\na circle with radius r.'
>>> print S.__doc__
This function returns the area of
a circle with radius r.

תיעוד מחלקה

תיעוד מחלקה מתבצע באמצעות כתיבת פונקציה פנימית מיוחדת בשם __doc__:

class Blabla:
	def __doc__(self):
		intro_str = "This is a general purpose class for doing..."
		doc_str   = "The version of this class can be retrieved " +\
				"by typing Blabla.version"
		return intro_str + '\n' + doc_str

ניתן תמיד לגשת לתיעוד בשתי דרכים: ישירה (ע"י הדפסת המשתנה __doc__) ועקיפה (ע"י שימוש בפונקציה help הפנימית של פייתון).

הערות תיעוד מובנה ובדיקות תוכנה

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

קיימת גם צורת הערות מתוחכמת יחסית, המשמשת לשימושים מתקדמים יותר:

1. יצירת תיעוד מהקוד על ידי כלים אוטומטיים
2. יצירת קוד בדיקה לנכונות קוד על ידי כלים אוטומטיים

קישורים חיצוניים

-

הערות

-