מחרוזות תיעוד

שיעור 8 מתוך 28 בקורס קוד נקי – כתיבת קוד טוב יותר באמצעות Python של Coddy.

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

מגדירים מחרוזת תיעוד על ידי עטיפת מחרוזת ב־""" או ב־''', לדוגמה,

def complex(real=0.0, imag=0.0):
	"""
	צור מספר מרוכב.
	
		Parameters:
			real (float) -- החלק הממשי (ברירת מחדל 0.0)
			imag (float) -- החלק המדומה (ברירת מחדל 0.0)
	"""
    if imag == 0.0 and real == 0.0:
        return complex_zero
    ...

שימו לב לאופן שבו היא מתעדת את הפונקציה complex(real, imag).

שימו לב להזחה של גוף התיעוד ושל """

לאחר שימוש במחרוזת תיעוד כך, אפשר להשתמש במאפיין __doc__ כדי לקבל את התיעוד,

complex.__doc__

הפלט יהיה,

Form a complex number.
	
	Parameters:
		real (float) -- the real part (default 0.0)
		imag (float) -- the imaginary part (default 0.0)

אתגר

קל

ניתנה לך פונקציה עם הערת בלוק במקום מחרוזת תיעוד.

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

נסו בעצמכם

def sum_binary(a, b):
    # Calculate sum of two integers in binary formmated string
    # Parameters:
    # a (int) -- Integer number
    # b (int) -- Another integer number
    # Returns:
    # binary_sum (str) -- The sum of a and b in binary format
    sum = a + b
    binary_sum = bin(sum)
    return str(binary_sum)[1:] # Final formmating

print(sum_binary.__doc__)