سلاسل التوثيق

الدرس 8 من 28 في دورة Clean Code - كتابة كود أفضل باستخدام Python على Coddy.

تحدث سلسلة التوثيق أو Docstring غالبًا بوصفها التعليمة الأولى في تعريف وحدة أو دالة أو فئة أو أسلوب.

أعلن عن سلسلة التوثيق بإحاطة السلسلة النصية بـ """ أو '''، على سبيل المثال،

def complex(real=0.0, imag=0.0):
	"""
	شكّل عددًا مركبًا.
	
		المعاملات:
			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__)