تنسيقات Docstring الشائعة في بايثون

عندما تكون منغمسًا تمامًا في أكواد بايثون، فإن التوثيق الشامل قد يكون بمثابة منقذ لك (ولكنه آخر شيء قد ترغب في كتابته). إنه جزء مهم من البرمجة، وبايثون، كونها لغة سهلة القراءة ومباشرة، تولي أهمية كبيرة لذلك.

أحد المكونات الرئيسية لوثائق بايثون هو سلسلة الوثائق، وهي ميزة فريدة تميز بايثون عن العديد من اللغات الأخرى. في هذه المقالة، سنتعمق في ماهية سلسلة الوثائق ونستكشف بعض تنسيقات سلسلة الوثائق الأكثر شيوعًا المستخدمة في بايثون.

ما هو 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

وإليك كيفية الوصول إلى سلسلة الوثائق:

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.

ملاحظة: يمكن أيضًا استخدام دالة help() المضمنة في بايثون للوصول إلى سلسلة توثيق دالة أو تابع أو فئة أو وحدة نمطية. على سبيل المثال، ستقوم الدالة help(add_numbers) بطباعة سلسلة توثيق مع بعض المعلومات الإضافية.

لا توجد حقًا قاعدة صارمة حول كيفية كتابة سلسلة توثيق، على الرغم من وجود العديد من التنسيقات المقبولة على نطاق واسع والتي تجعل سلاسل الوثائق أكثر هيكلة وفائدة. لا تساعد هذه التنسيقات في فهم الكود فحسب، بل إنها تسمح أيضًا لأدوات مثل Sphinx وPyDoc وDoxygen بإنشاء وثائق بتنسيق جيد تلقائيًا.

سننظر إلى هذه التنسيقات في الأقسام التالية.

تنسيقات Docstring الشائعة في بايثون

تُعد سلاسل الوثائق في بايثون أداة فعّالة لتوثيق الكود الخاص بك. وهي عبارة عن تعليقات مكتوبة بتنسيق محدد، مما يسمح بتحليلها بواسطة أدوات إنشاء الوثائق. هناك العديد من التنسيقات الشائعة لكتابة سلاسل الوثائق، ولكل منها نقاط قوة ونقاط ضعف خاصة بها. التنسيقات الأكثر استخدامًا هي reStructuredText (reST)، وGoogle، وNumPy/SciPy، وEpytext.

ملاحظة: من المهم أن تضع في اعتبارك أن أفضل تنسيق لسلسلة الوثائق بالنسبة لك يعتمد على حالة الاستخدام الخاصة بك. يجب أن تأخذ في الاعتبار عوامل مثل تعقيد الكود الخاص بك، والأدوات التي تستخدمها لإنشاء الوثائق، وتفضيلاتك الشخصية.

تنسيق سلسلة توثيق النص المعاد هيكلته (reST)

ReStructuredText، والذي يُشار إليه غالبًا باسم reST، هو تنسيق ملف للبيانات النصية المستخدمة بشكل أساسي في مجتمع بايثون للوثائق الفنية. إنها لغة ترميز النص العادي الافتراضية التي يستخدمها Sphinx، وهو مولد وثائق بايثون.

في سلسلة توثيق reST، ستبدأ عادةً بوصف موجز لغرض الدالة. ثم ستدرج أقسامًا لـ :param: لوصف معلمات الإدخال، و :returns: لوصف قيمة الإرجاع، و :raises: لوصف أي استثناءات قد تثيرها الدالة.

فيما يلي مثال لكيفية ظهور سلسلة توثيق reST:

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

في هذا المثال، يبدأ نص التوثيق بوصف موجز للدالة. ثم يستخدم :param: لوصف معلمات الإدخال x وy، و :type: لتحديد أنواعها، و :returns: لوصف قيمة الإرجاع، و :raises: لوصف استثناء ValueError الذي قد تثيره الدالة.

ملاحظة: باستخدام reST، يمكنك أيضًا تضمين أقسام أخرى مثل :example: للحصول على أمثلة على الاستخدام، و:seealso: للدوال ذات الصلة، و:note: للحصول على ملاحظات إضافية. وهذا يجعلها أداة توثيق مرنة وشاملة للغاية.

تنسيق سلسلة توثيق Google

تنسيق 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

تنسيق NumPy/SciPy Docstring هو تنسيق شائع آخر، وخاصة بين مجتمعات الحوسبة العلمية. فهو يوفر طريقة منظمة لتوثيق كود بايثون ويتميز باستخدامه المكثف للأقسام والأقسام الفرعية، مما يجعله مناسبًا لتوثيق الكود المعقد.

فيما يلي مثال لدالة موثقة باستخدام تنسيق Docstring الخاص بـ NumPy/SciPy:

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 النتيجة التي تعيدها الدالة، إلى جانب نوعها. يعد استخدام الشرطات (——) لفصل الأقسام سمة مميزة لهذا التنسيق.

ملاحظة: تدعم أدوات متنوعة لإنشاء الوثائق، مثل Sphinx وPydoc، تنسيقي Docstring الخاصين بـ Google وNumPy/SciPy. وهذا يعني أنه يمكنك إنشاء HTML أو PDF أو تنسيقات أخرى من الوثائق تلقائيًا من سلاسل وثائق بايثون الخاصة بك.

تنسيق سلسلة توثيق EpYtext

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.

ثالثًا، ضع في اعتبارك مدى سهولة قراءة تنسيق سلسلة الوثائق. يجد بعض المطورين أن بعض التنسيقات أسهل في القراءة والكتابة من غيرها. على سبيل المثال، يجد بعض الأشخاص أن تنسيق سلسلة وثائق Google أسهل في القراءة من تنسيق reST.

فيما يلي مقارنة سريعة بين تنسيقات سلاسل الوثائق الأربعة التي ناقشناها:

• reST:  ذو هيكل عالي، مثالي للمشاريع المعقدة، ودعم ممتاز في Sphinx.
• جوجل: أقل هيكلة، وسهل القراءة والكتابة، ودعم جيد في أدوات مختلفة.
• NumPy/SciPy: منظم للغاية، رائع للمشاريع العلمية، دعم ممتاز في Sphinx.
• EpYtext: أقل هيكلة، سهل القراءة والكتابة، ودعم جيد في Epydoc.

تذكر أن أهم شيء هو توثيق الكود الخاص بك. التنسيق المحدد الذي تختاره أقل أهمية من عملية التوثيق نفسها.

في هذه المقالة، قمنا بالتعمق في عالم سلاسل توثيق بايثون واستكشفنا بعض التنسيقات الأكثر شيوعًا التي يستخدمها المطورون لتوثيق التعليمات البرمجية الخاصة بهم. لقد نظرنا في تنسيقات سلاسل توثيق ReStructured Text (reST)، وGoogle، وNumPy/SciPy، وEpytext، وكل منها له أنماطه واتفاقياته الفريدة.

يعتمد اختيار تنسيق سلسلة الوثائق الصحيحة إلى حد كبير على احتياجات مشروعك المحددة وتفضيلاتك الشخصية. سواء كنت تفضل بساطة أسلوب Google أو البنية التفصيلية لـ reST أو التركيز الرياضي لـ NumPy/SciPy، فتذكر أن مفتاح التوثيق الجيد هو الاتساق والوضوح. طالما أن سلاسل الوثائق الخاصة بك واضحة وموجزة ومتسقة، فسوف تعمل كدليل مفيد لك وللمطورين الآخرين الذين يتفاعلون مع الكود الخاص بك.