کد خوب شامل نظراتی برای کمک به درک آن است و رشته‌های اسنادی می‌توانند نقش مهمی در آن داشته باشند.
بدون مستندات مناسب، درک، نگهداری و اشکال زدایی کد شما می تواند دشوار باشد. در پایتون، می‌توانید از رشته‌های اسنادی برای ارائه توضیحات مختصر و مثال‌هایی از نحوه عملکرد کد استفاده کنید.
Docstrings چیست؟
Docstrings رشته‌هایی هستند که می‌توانید به کد پایتون خود اضافه کنید تا توضیح دهید که چه کار می‌کند و چگونه از آن استفاده کنید. قطعه کد می تواند یک تابع پایتون، یک ماژول یا یک کلاس باشد.
Docstrings شباهت زیادی به نظرات استاندارد پایتون دارد، اما تفاوت هایی با هم دارند. نظرات پایتون اطلاعات بیشتری را در مورد عملکرد درونی کد به توسعه دهندگان ارائه می دهد، مانند جزئیات پیاده سازی یا نکاتی که باید هنگام گسترش کد در نظر داشته باشید.
از سوی دیگر، رشته‌های اسنادی عمدتاً اطلاعاتی را در اختیار کاربران کد قرار می‌دهند که ممکن است لزوماً نیازی به دانستن جزئیات پیاده‌سازی آن نداشته باشند، اما باید بدانند چه کاری انجام می‌دهد و چگونه از آن استفاده کنند.
نحوه نوشتن Docstrings
شما معمولاً رشته‌های اسناد را در ابتدای بلوک کدی که می‌خواهید مستند کنید، اضافه می‌کنید. شما باید آنها را در گیومه های سه گانه (“”) قرار دهید.
رشته‌های اسناد تک خطی برای کدهای ساده که نیازی به مستندات زیادی ندارند، مناسب هستند.
در زیر نمونه ای از تابعی به نام ضرب را مشاهده می کنید. رشته docstring توضیح می‌دهد که تابع ضرب دو عدد می‌گیرد، آنها را ضرب می‌کند و نتیجه را برمی‌گرداند.
def multiply(a, b):
"""Multiplies two numbers and returns the result"""
return a * b
از رشته‌های اسناد چند خطی برای کدهای پیچیده‌تر که نیاز به مستندات دقیق دارند، استفاده کنید.
کلاس اتومبیل زیر را در نظر بگیرید:
class Car:
"""
A class representing a car object.
Attributes:
mileage (float): The current mileage of the car.
Methods:
drive(miles): Drives the car for the specified number of miles.
"""
def __init__(self, mileage):
self.mileage = mileage
def drive(self, miles):
"""
Drives the car for the specified number of miles.
Args:
miles (float): The number of miles to drive.
Returns:
None
"""
self.mileage += miles
رشته docstring برای کلاس فوق توضیح می دهد که کلاس چه چیزی را نشان می دهد، ویژگی های آن و روش های آن. در همین حال، رشته‌های docstrings برای متد درایو اطلاعاتی در مورد کارهایی که متد انجام می‌دهد، آرگومان‌هایی که انتظار دارد و آنچه را که برمی‌گرداند ارائه می‌دهد.
این امر درک نحوه استفاده از آن را برای هر کسی که با این کلاس کار می کند آسان تر می کند. مزایای دیگر استفاده از docstrings عبارتند از:
- قابلیت نگهداری کد: با ارائه توضیح واضحی از نحوه عملکرد کد، رشته‌های اسناد به توسعه‌دهندگان کمک می‌کنند تا کد را بدون ارائه خطا اصلاح و به‌روزرسانی کنند.
- همکاری آسان‌تر: زمانی که چندین توسعه‌دهنده بر روی یک پایه کد با هم همکاری می‌کنند – به عنوان مثال، با ابزار اشتراک‌گذاری زنده ویژوال استودیو – رشته‌های اسناد به توسعه‌دهندگان اجازه می‌دهند تا کد را به‌طور مداوم مستند کنند تا همه اعضای تیم بتوانند آن را درک کنند.
- خوانایی کد بهبود یافته: Docstrings خلاصه‌ای در سطح بالا از آنچه کد انجام می‌دهد ارائه می‌کند که به هر کسی که کد را می‌خواند اجازه می‌دهد به سرعت هدف آن را بدون عبور از کل بلوک کد درک کند.
فرمت های Docstring
یک Docstring خوب باید آنچه را که یک قطعه کد انجام می دهد، آرگومان هایی که انتظار دارد و جزئیات پیاده سازی را در صورت لزوم شرح دهد. به ویژه باید شامل موارد لبه باشد که هر کسی که از کد استفاده می کند باید از آن آگاه باشد.
یک قالب Docstring پایه دارای بخش های زیر است:
- خط خلاصه: خلاصه ای یک خطی از کاری که کد انجام می دهد.
- آرگومان ها: اطلاعاتی در مورد آرگومان هایی که تابع انتظار دارد از جمله انواع داده های آنها.
- مقدار بازگشتی: اطلاعات مربوط به مقدار بازگشتی تابع از جمله نوع داده آن.
- افزایش (اختیاری): اطلاعات در مورد استثناهایی که تابع ممکن است ایجاد کند.
این فقط یک قالب اولیه است زیرا فرمت های دیگری وجود دارد که می توانید برای پایه رشته های اسناد خود انتخاب کنید. محبوب ترین آنها عبارتند از Epytext، reStructuredText (همچنین به عنوان reST شناخته می شود)، NumPy و Google docstrings. هر یک از این فرمت ها نحو خاص خود را دارند که در مثال های زیر نشان داده شده است:
متن متنی
یک رشته مستند که از فرمت Epytext پیروی می کند:
def multiply(a, b):
"""
Multiply two numbers together.
@param a: The first number to multiply.
@type a: int
@param b: The second number to multiply.
@type b: int
@return: The product of the two numbers.
@rtype: int
"""
return a * b
reStructuredText (reST)
یک رشته مستند که از فرمت reST پیروی می کند:
def multiply(a, b):
"""
Multiply two numbers together.
:param a: The first number to multiply.
:type a: int
:param b: The second number to multiply.
:type b: int
:return: The product of the two numbers.
:rtype: int
"""
return a * b
NumPy
یک رشته مستند که از فرمت NumPy پیروی می کند:
def multiply(a, b):
"""
Multiply two numbers together.
Parameters
----------
a : int
The first number to multiply.
b : int
The second number to multiply.
Returns
-------
int
The product of the two numbers.
"""
return a * b
گوگل
یک رشته مستند که از قالب Google پیروی می کند:
def multiply(a, b):
"""
Multiply two numbers together.
Args:
a (int): The first number to multiply.
b (int): The second number to multiply.
Returns:
int: The product of the two numbers.
"""
return a * b
اگرچه هر چهار فرمت docstring مستندات مفیدی را برای تابع ضرب ارائه می‌کنند، فرمت‌های NumPy و Google راحت‌تر از فرمت‌های Epytext و reST خوانده می‌شوند.
نحوه گنجاندن تست ها در Docstrings
می توانید با استفاده از ماژول doctest نمونه های آزمایشی را در رشته های مستند خود قرار دهید. ماژول doctest رشته docstring را برای متنی که شبیه جلسات پایتون تعاملی است جستجو می‌کند و سپس آنها را اجرا می‌کند تا تأیید کند که همانطور که باید کار می‌کنند.
برای استفاده از doctest ها، ورودی های نمونه و خروجی های مورد انتظار را در رشته docstring قرار دهید. در زیر مثالی از نحوه انجام این کار آورده شده است:
def multiply(a, b):
"""
Multiply two numbers together.
Parameters
----------
a : int
The first number to multiply.
b : int
The second number to multiply.
Returns
-------
int
The product of the two numbers.
Examples
--------
>>> multiply(2, 3)
6
>>> multiply(0, 10)
0
>>> multiply(-1, 5)
-5
"""
return a * b
بخش Examples شامل سه فراخوانی تابع با آرگومان های مختلف است و خروجی مورد انتظار برای هر کدام را مشخص می کند. هنگامی که ماژول doctest را مطابق شکل زیر اجرا می کنید، نمونه ها را اجرا می کند و خروجی واقعی را با خروجی مورد انتظار مقایسه می کند.
python -m doctest multiply.py
در صورت وجود هر گونه تفاوت، ماژول doctest آنها را به عنوان خرابی گزارش می کند. استفاده از doctests با رشته‌های اسنادی مانند این به شما کمک می‌کند تا بررسی کنید که کد مطابق انتظار کار می‌کند. توجه داشته باشید که doctest ها جایگزینی برای تست های واحد جامع تر و تست های یکپارچه سازی کد پایتون شما نیستند.
نحوه تولید اسناد از Docstrings
شما اصول استفاده از رشته‌های اسنادی برای مستندسازی کد پایتون و اهمیت اسناد با کیفیت بالا را یاد گرفته‌اید. برای ارتقاء سطح، ممکن است بخواهید مستنداتی را برای ماژول ها و توابع خود از رشته های مستند مربوطه ایجاد کنید.
یکی از محبوب ترین مولدهای مستندسازی که می توانید استفاده کنید Sphinx است. به طور پیش‌فرض از فرمت reST docstring پشتیبانی می‌کند، اما می‌توانید آن را طوری پیکربندی کنید که با فرمت Google یا NumPy کار کند.