פייתון/הערות

מתוך ויקיספר, אוסף ספרי הלימוד והמדריכים החופשי.

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

[עריכה] הערות שורה

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

# 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

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

>>> 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

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

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

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

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

[עריכה] קישורים חיצוניים

1. ↑ pydoc -- Documentation generator and online help system
2. ↑ doctest -- Test interactive Python examples