فرمت های رایج Docstring در پایتون

معرفی

وقتی تا زانو در کد پایتون هستید، مستندات جامع می تواند نجات دهنده باشد (اما مسلما آخرین چیزی است که می خواهید بنویسید). این بخش مهمی از برنامه نویسی است و پایتون به دلیل اینکه زبانی بسیار خوانا و ساده است، تاکید زیادی دارد. روی آی تی.

یکی از مؤلفه‌های کلیدی اسناد پایتون، docstring است، ویژگی منحصر به فردی که پایتون را از بسیاری از زبان‌های دیگر متمایز می‌کند. در این مقاله، ما در مورد اینکه Docstring چیست و برخی از رایج‌ترین قالب‌های docstring مورد استفاده در پایتون را بررسی می‌کنیم.

Docstring چیست؟

Docstring که مخفف رشته documentation است، رشته‌ای است که بلافاصله پس از تعریف تابع، متد، کلاس یا ماژول استفاده می‌شود. این ماهیت کاری که تابع انجام می دهد را در بر می گیرد و یک مرجع آسان برای برنامه نویس فراهم می کند. در پایتون، یک docstring یک شهروند درجه یک است، به این معنی که می توان به صورت برنامه نویسی با استفاده از __doc__ صفت.

در اینجا یک تابع ساده پایتون با یک رشته مستند وجود دارد:

def add_numbers(a, b):
    """
    Adds two numbers together.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of the two numbers.
    """
    return a + b

و در اینجا روش دسترسی به docstring آورده شده است:

print(add_numbers.__doc__)

خروجی خواهد بود:

Adds two numbers together.

Args:
    a (int): The first number.
    b (int): The second number.

Returns:
    int: The sum of the two numbers.

واقعا هیچ قانون سختگیرانه ای وجود ندارد روی روش نوشتن یک Docstring، اگرچه چندین فرمت به طور گسترده پذیرفته شده باعث می شود که رشته اسناد ساختارمندتر و مفیدتر باشد. این فرمت‌ها نه تنها به درک کد کمک می‌کنند، بلکه به ابزارهایی مانند Sphinx، PyDoc و Doxygen نیز اجازه می‌دهند تا به‌طور خودکار اسنادی با فرمت مناسب تولید کنند.

در بخش های بعدی به بررسی این فرمت ها خواهیم پرداخت.

فرمت های رایج Docstring پایتون

Docstrings در پایتون ابزاری قدرتمند برای مستندسازی کد شماست. آنها اساسا نظراتی هستند که در قالب خاصی نوشته شده اند، که به آنها امکان می دهد توسط ابزارهای تولید اسناد تجزیه شوند. چندین فرمت رایج برای نوشتن رشته های مستند وجود دارد و هر کدام نقاط قوت و ضعف خاص خود را دارند. رایج ترین فرمت های مورد استفاده عبارتند از reStructuredText (reST)، Google، NumPy/SciPy و Epytext.

قالب Docstring متن بازسازی شده (reST).

ReStructuredText، که اغلب به عنوان reST مخفف می شود، یک فرمت فایل برای داده های متنی است که عمدتاً در جامعه Python برای اسناد فنی استفاده می شود. این زبان نشانه گذاری متن ساده پیش فرض است که توسط Sphinx، یک تولید کننده اسناد پایتون استفاده می شود.

در یک reST docstring، معمولاً با توضیح مختصری از هدف تابع شروع می‌کنید. سپس بخش هایی را برای :param: برای توصیف پارامترهای ورودی، :returns: برای توصیف مقدار بازگشتی، و :raises: برای توصیف هر استثنایی که تابع ممکن است ایجاد کند.

در اینجا مثالی از شکلی است که یک reST docstring ممکن است شبیه باشد:

def add_numbers(x, y):
    """
    Adds two numbers together.

    :param x: The first number to add
    :type x: int or float
    :param y: The second number to add
    :type y: int or float
    :returns: The sum of x and y
    :rtype: int or float
    :raises ValueError: If either x or y is not an int or float
    """
    if not isinstance(x, (int, float)) or not isinstance(y, (int, float)):
        raise ValueError('Both x and y must be ints or floats')
    return x + y

در این مثال، رشته docstring با توضیح مختصری از تابع شروع می شود. سپس استفاده می کند :param: برای توصیف پارامترهای ورودی x و y، :type: برای مشخص کردن انواع آنها، :returns: برای توصیف مقدار بازگشتی، و :raises: برای توصیف ValueError استثنایی که تابع ممکن است افزایش دهد.

فرمت Google Docstring

فرمت Google Docstring به دلیل خوانایی و سادگی یک انتخاب محبوب در بین توسعه دهندگان پایتون است. این قالب با تفکیک واضح بخش ها مشخص می شود که با سربرگ بخش ها نشان داده می شود. سرفصل های بخش شامل Args، Returns، Raises، Yields، و Attributes، بین دیگران.

در اینجا مثالی از یک تابع مستند شده با استفاده از قالب Google Docstring آورده شده است:

def add_numbers(a, b):
    """
    Adds two numbers together.

    Args:
        a (int): The first number.
        b (int): The second number.

    Returns:
        int: The sum of a and b.
    """
    return a + b

اینجا Args بخش آرگومان هایی را که تابع انتظار دارد، از جمله نوع و هدف آنها را شرح می دهد. این Returns بخش، روی از سوی دیگر، نتیجه ای را که تابع برمی گرداند همراه با نوع آن توصیف می کند.

فرمت NumPy/SciPy Docstring

فرمت NumPy/SciPy Docstring یکی دیگر از فرمت های محبوب، به ویژه در میان جوامع محاسباتی علمی است. این روشی ساختاریافته برای مستندسازی کد پایتون ارائه می‌کند و با استفاده گسترده از بخش‌ها و بخش‌های فرعی مشخص می‌شود، که آن را برای مستندسازی کدهای پیچیده مناسب می‌کند.

در اینجا یک مثال از یک تابع مستند شده با استفاده از فرمت NumPy/SciPy Docstring آورده شده است:

def add_numbers(a, b):
    """
    Adds two numbers together.

    Parameters
    ----------
    a : int
        The first number.
    b : int
        The second number.

    Returns
    -------
    int
        The sum of a and b.
    """
    return a + b

در این مثال، Parameters بخش پارامترهای تابع، از جمله نوع و هدف آنها را توضیح می دهد. این Returns بخش نتیجه ای را که تابع برمی گرداند به همراه نوع آن توضیح می دهد. استفاده از خط تیره (------) جدا کردن بخش ها از ویژگی های بارز این قالب است.

فرمت EpYtext Docstring

EpYtext یکی دیگر از فرمت‌های مستند محبوب مورد استفاده در پایتون است. این یک قالب متن ساده برای رشته‌های اسناد پایتون است که به عنوان بخشی از پروژه Epydoc توسعه یافته است. زبان نشانه گذاری Epytext به گونه ای طراحی شده است که خواندن و نوشتن به شکل خام آن آسان باشد و در عین حال به راحتی در فرمت های خروجی مختلف ارائه شود.

در اینجا مثالی از روش استفاده از قالب مستند EpYtext آورده شده است:

def add_numbers(a, b):
    """
    This function adds two numbers.

    @param a: The first number.
    @type a: C{int}
    @param b: The second number.
    @type b: C{int}
    @return: The sum of the two numbers.
    @rtype: C{int}
    """
    return a + b

در مثال بالا، می بینید که فرمت EpYtext از آن استفاده می کند @تگ های سبک برای نشان دادن بخش های مختلف رشته مستند. این @param و @type از تگ ها برای مستندسازی پارامترهای تابع استفاده می شود، در حالی که @return و @rtype تگ ها برای مستند کردن مقدار بازگشتی تابع استفاده می شوند.

انتخاب فرمت Docstring مناسب

انتخاب قالب مستند رشته ای مناسب تا حد زیادی به اولویت شخصی و نیازهای خاص پروژه شما بستگی دارد. با این حال، هنگام تصمیم گیری باید چند نکته را در نظر بگیرید.

ابتدا پیچیدگی پروژه خود را در نظر بگیرید. اگر پروژه شما بزرگ و پیچیده است، یک قالب مستند ساختارمندتر مانند reST یا NumPy/SciPy ممکن است مفید باشد. این فرمت‌ها امکان مستندات دقیق‌تری را فراهم می‌کنند، که به ویژه در پایگاه‌های کد بزرگ می‌تواند مفید باشد.

در مرحله دوم، ابزارهایی را که استفاده می کنید در نظر بگیرید. برخی از ابزارهای تولید اسناد، مانند Sphinx، پشتیبانی بهتری از فرمت‌های رشته مستند خاص دارند. به عنوان مثال، Sphinx از فرمت reST docstring پشتیبانی داخلی دارد.

سوم، خوانایی فرمت docstring را در نظر بگیرید. برخی از توسعه دهندگان فرمت های خاصی را برای خواندن و نوشتن آسان تر از دیگران می دانند. برای مثال، برخی افراد فرمت docstring گوگل را خواناتر از قالب reST می دانند.

در اینجا یک مقایسه سریع از چهار فرمت docstring که در مورد آن بحث کردیم آورده شده است:

• باقی مانده: ساختار بسیار بالا، عالی برای پروژه های پیچیده، پشتیبانی عالی در Sphinx.
• گوگل: ساختار کمتر، خواندن و نوشتن آسان، پشتیبانی خوب در ابزارهای مختلف.
• NumPy/SciPy: ساختار بسیار بالا، عالی برای پروژه های علمی، پشتیبانی عالی در Sphinx.
• EpYtext: ساختار کمتر، خواندن و نوشتن آسان، پشتیبانی خوب در Epydoc.

به یاد داشته باشید، مهمترین چیز این است که شما در حال مستندسازی کد خود هستید. قالب خاصی که انتخاب می کنید اهمیت کمتری نسبت به خود سند دارد.

نتیجه

در این مقاله، ما به دنیای اسناد پایتون نگاهی عمیق انداخته‌ایم و برخی از رایج‌ترین فرمت‌هایی را که توسعه‌دهندگان برای مستندسازی کد خود استفاده می‌کنند، بررسی کرده‌ایم. ما قالب‌های Docstring Text ReStructured (reST)، Google، NumPy/SciPy و Epytext را بررسی کرده‌ایم که هر کدام سبک‌ها و قراردادهای منحصر به فرد خود را دارند.

انتخاب قالب مستند رشته ای مناسب تا حد زیادی بستگی دارد روی نیازهای پروژه خاص و ترجیح شخصی شما. خواه سادگی سبک گوگل، ساختار دقیق reST، یا تمرکز ریاضی NumPy/SciPy را ترجیح می دهید، به یاد داشته باشید که کلید مستندسازی خوب، سازگاری و وضوح است. تا زمانی که رشته‌های اسناد شما واضح، مختصر و منسجم باشند، هم برای شما و هم برای توسعه‌دهندگان دیگری که با کد شما تعامل دارند، به عنوان راهنمای مفیدی عمل خواهند کرد.