Python docstring पूर्ण गाइड: लेखन शैली र सर्वोत्तम अभ्यास

1. Python को docstring के हो?

docstring को स्थान र स्वरूप

def 関数名(引数):
    """
    यहाँ कार्यको छोटो विवरण लेख्नुहोस्।

    आर्गुमेन्ट:
        परिमाणको नाम (प्रकार): परिमाण सम्बन्धी विस्तृत विवरण
    रिटर्न मान:
        प्रकार: फिर्ती मान सम्बन्धी विवरण
    """
    pass

2. docstring को आधारभूत लेखन तरिका

आधारभूत docstring को संरचना

def add(a, b):
    """दुई संख्याहरूलाई जोडेर परिणाम फिर्ता गर्दछ।"""
    return a + b

def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर, त्यसको परिणाम फिर्ता गर्दछ।

    आर्ग्युमेन्टहरू:
        a (int): जोडिने पहिलो संख्या
        b (int): जोडिने दोस्रो संख्या

    रिटर्न मान:
        int: दुई संख्याहरूको योग
    """
    return a + b

3. docstring को शैली（Google शैली、NumPy शैली、reStructuredText शैली）

Google शैली

def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर फिर्ता गर्छ।

    Args:
        a (int): जोडिने पहिलो संख्या
        b (int): जोडिने दोस्रो संख्या

    Returns:
        int: दुई संख्याहरूको योग
    """
    return a + b

NumPy शैली

def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर फिर्ता गर्छ।

    Parameters
    ----------
    a : int
        जोडिने पहिलो संख्या
    b : int
        जोडिने दोस्रो संख्या

    Returns
    -------
    int
        दुई संख्याहरूको योग
    """
    return a + b

reStructuredText शैली

def add(a, b):
    """
    दुई संख्याहरूलाई जोड्छ।

    :param a: जोडिने पहिलो संख्या
    :type a: int
    :param b: जोडिने दोस्रो संख्या
    :type b: int
    :return: दुई संख्याहरूको योग
    :rtype: int
    """
    return a + b

4. PEP 257 र सर्वश्रेष्ठ अभ्यासहरू

PEP 257 को महत्वपूर्ण बुँदाहरू

1. एक पङ्क्तिको docstring साधारण फङ्सन वा मेथडहरूका लागि, एक पङ्क्तिमा संक्षिप्त व्याख्या लेख्न सिफारिस गरिन्छ।
2. बहु-पङ्क्तिको docstring विस्तृत व्याख्या आवश्यक परेमा, बहु-पङ्क्तिको docstring प्रयोग गरिन्छ। यस अवस्थामा, पहिलो पङ्क्ति सानो सारांश हो, त्यसपछि खाली पङ्क्ति राखी विस्तृत व्याख्या लेखिन्छ।
3. इन्डेन्ट र खाली पङ्क्तिको प्रयोग docstring भित्र, लाइनब्रेक र इन्डेन्ट प्रयोग गरेर पढ्नयोग्यता बढाइन्छ। साथै, फङ्सनका आर्गुमेन्ट र रिटर्न मानको जानकारीलाई स्पष्ट रूपमा विभाजन गरेर, पढ्न सजिलो बनाइन्छ।

सर्वश्रेष्ठ अभ्यासहरू

• संक्षिप्त र स्पष्ट व्याख्या docstring संक्षिप्त भए पनि, फङ्सन वा क्लास के गर्छ भन्ने कुरा ठीकसँग बताउनुपर्छ। अनावश्यक जानकारी हटाउँदै, महत्वपूर्ण भागलाई विस्तृत रूपमा लेखौं।
• एकरूप शैलीको कायम राख्नु पूरा प्रोजेक्टमा docstring को शैलीलाई एकरूप बनाउँदा, पढ्नयोग्यता सुधार हुन्छ। Google शैली, NumPy शैली जस्ता, टिम वा प्रोजेक्टको लागि उपयुक्त शैली चयन गरौं।

5. docstring प्रयोग गरेर परीक्षण（doctest）

doctest को आधारभूत प्रयोग

def add(a, b):
    """
    दुई संख्याहरूलाई जोडेर फिर्ता गर्छ।

    Args:
        a (int): पहिलो संख्या
        b (int): दोस्रो संख्या

    Returns:
        int: दुई संख्याहरूको योग

    Example:
        >>> add(2, 3)
        5
        >>> add(0, 0)
        0
    """
    return a + b

if __name__ == "__main__":
    import doctest
    doctest.testmod()

doctest प्रयोग गर्ने फाइदाहरू

1. कोडको स्थिरता doctest प्रयोग गरेर, docstring भित्र लेखिएको नमुना कोड वास्तवमा चल्छ कि छैन जाँच गर्न सकिन्छ, जसले कोड र दस्तावेजको स्थिरता कायम राख्छ। यसले दस्तावेजलाई सधैं नवीनतम कोडसँग मिल्दो बनाउँछ।
2. परीक्षणको स्वालन doctest सजिलै स्वचालित गर्न सकिन्छ, र फङ्क्शन वा क्लासको परीक्षण म्यानुअली गर्न आवश्यक छैन। केवल doctest चलाएमा, docstring भित्रका सबै कोड उदाहरणहरू परीक्षण हुन्छन्, जसले त्रुटिहरू घटाउँछ।

6. व्यावहारिक उदाहरण: docstring लाई प्रयोग गरेर कोडको दस्तावेजीकरण

वर्गको लागि docstring लेखन उदाहरण

class Calculator:
    """
    सरल क्याल्कुलेटर वर्ग।

    यो वर्गले आधारभूत जोड, घटाउ, गुणा, भाग कार्यहरू गर्दछ।

    Attributes:
        result (int): गणनाको परिणाम राख्ने चल
    """

    def __init__(self):
        """
        Calculator वर्गको कन्स्ट्रक्टर।
        प्रारम्भ गर्दा परिणामलाई 0 मा सेट गरिन्छ।
        """
        self.result = 0

    def add(self, a, b):
        """
        दुई संख्याहरूलाई जोडेर, परिणाम फिर्ता गर्दछ।

        Args:
            a (int): पहिलो संख्या
            b (int): दोस्रो संख्या

        Returns:
            int: दुई संख्याहरूको योग
        """
        self.result = a + b
        return self.result

Sphinx प्रयोग गरेर दस्तावेज निर्माण

pip install sphinx

7. सामान्य त्रुटिहरू र तिनीहरूको समाधान तरिका

1. अस्पष्ट व्याख्या

def add(a, b):
    """दुई संख्याहरूलाई जोड्छ।"""
    return a + b

def add(a, b):
    """
    दुई पूर्णांकहरूलाई जोडेर, नतिजा फिर्ता गर्छ।

    Args:
        a (int): पहिलो संख्या
        b (int): दोस्रो संख्या

    Returns:
        int: दुई संख्याहरूको योग
    """
    return a + b

2. आर्गुमेन्ट वा रिटर्न मानको असठीक विवरण

def divide(a, b):
    """दुई संख्याहरूलाई भाग गर्छ।"""
    return a / b

def divide(a, b):
    """
    दुई संख्याहरूलाई भाग गरी, नतिजा फिर्ता गर्छ। 0 ले भाग गर्दा ZeroDivisionError उत्पन्न हुन्छ।

    Args:
        a (float): भागिने संख्या
        b (float): भाग गर्ने संख्या

    Returns:
        float: भागफलको नतिजा

    Raises:
        ZeroDivisionError: 0 ले भाग गर्ने प्रयास गर्दा
    """
    if b == 0:
        raise ZeroDivisionError("0 ले भाग गर्न सकिँदैन")
    return a / b

8. सारांश: docstring प्रयोग गरेर प्रभावकारी दस्तावेज़ निर्माण

PEP 257 मा आधारित एकरूप दस्तावेज़ निर्माण

doctest को उपयोगद्वारा नमूना कोडको परीक्षण

Sphinx प्रयोग गरेर दस्तावेज़को स्वचालित निर्माण